Author: chris.laprun(a)jboss.com Date: 2008-07-09 16:39:40 -0400 (Wed, 09 Jul 2008) New Revision: 11387 Modified: modules/common/trunk/common/src/main/java/org/jboss/portal/common/util/Tools.java Log: - Javadoc + reformat. Modified: modules/common/trunk/common/src/main/java/org/jboss/portal/common/util/Tools.java =================================================================== --- modules/common/trunk/common/src/main/java/org/jboss/portal/common/util/Tools.java 2008-07-09 19:43:37 UTC (rev 11386) +++ modules/common/trunk/common/src/main/java/org/jboss/portal/common/util/Tools.java 2008-07-09 20:39:40 UTC (rev 11387) @@ -38,6 +38,7 @@ import java.security.NoSuchAlgorithmException; import java.util.ArrayList; import java.util.Calendar; +import java.util.Collections; import java.util.Enumeration; import java.util.HashSet; import java.util.Iterator; @@ -46,7 +47,6 @@ import java.util.NoSuchElementException; import java.util.ResourceBundle; import java.util.Set; -import java.util.Collections; /** * @author <a href="mailto:julien@jboss.org">Julien Viet</a> @@ -270,7 +270,7 @@ /** * Transforms an iterator into a Set * - * @param iterator The iterator to transform + * @param iterator The iterator to transform * @param preserveOrder true if the set must respect the ordering of the iterator * @return a LinkedHashSet if ordered is true, a HashSet otherwise */ @@ -403,15 +403,16 @@ } /** - * Returns an iterator over the array elements within the specified range. The range is considered as valid - * if the from argument is greater or equals than zero, the to argument is lesser or equals than array size - * and the from argument is lesser or equals to the to argument. + * Returns an iterator over the array elements within the specified range. The range is considered as valid if the + * from argument is greater or equals than zero, the to argument is lesser or equals than array size and the from + * argument is lesser or equals to the to argument. * * @param objects the array containing the objects to iterate on * @param from the inclusive start index * @param to the exclusive stop index * @return the iterator - * @throws IllegalArgumentException if the object array is null or the specified range is not valid or if the range is not valid + * @throws IllegalArgumentException if the object array is null or the specified range is not valid or if the range + * is not valid */ public static <E> Iterator<E> iterator(final E[] objects, final int from, final int to) throws IllegalArgumentException { @@ -785,16 +786,15 @@ } /** - * Append an object to an array of objects. The original array is not modified. The returned array - * will be of the same component type of the provided array and its first n elements where n is the size - * of the provided array will be the elements of the provided array. The last element of the array will be - * the provided object to append. + * Append an object to an array of objects. The original array is not modified. The returned array will be of the + * same component type of the provided array and its first n elements where n is the size of the provided array will + * be the elements of the provided array. The last element of the array will be the provided object to append. * * @param array the array to augment - * @param o the object to append + * @param o the object to append * @return a new array * @throws IllegalArgumentException if the array is null - * @throws ClassCastException if the appended object class prevents it from being added to the array + * @throws ClassCastException if the appended object class prevents it from being added to the array */ public static <E> E[] appendTo(E[] array, E o) throws IllegalArgumentException, ClassCastException { @@ -822,7 +822,7 @@ /** * Return true if * <ul> - * <li>o1 is null and o2 is null</li< + * <li>o1 is null and o2 is null</li> * <li>o1 is not null and the invocation of <code>equals(Object o)</code> on o1 wit o2 as argument returns true</li> * </ul> * @@ -842,22 +842,39 @@ } } - public static String replaceAllInstancesOfBoundedString(String initial, String prefix, String suffix, String replacement) - { - return replaceBoundedString(initial, prefix, suffix, replacement, true, false); - } - /** - * Todo : define what "bounded" means. + * Same as replaceBoundedString(initial, prefix, suffix, replacement, true, false). * * @param initial * @param prefix * @param suffix * @param replacement - * @param replaceIfBoundedStringEmpty - * @param keepBoundaries * @return */ + public static String replaceAllInstancesOfBoundedString(String initial, String prefix, String suffix, String replacement) + { + return replaceBoundedString(initial, prefix, suffix, replacement, true, false); + } + + /** + * Replace instances of Strings delimited by the given prefix and suffix (hence, bounded) by the specified + * replacement String. It is possible to specify whether the substitution will happen only if the delimited String is + * non-empty by setting <code>replaceIfBoundedStringEmpty</code> to <code>false</code>. It is also possible to keep + * the boundaries (prefix and suffix) after the substitution by setting <code>keepBoundaries</code> to + * <code>true</code>. + * <p/> + * See org.jboss.portal.test.common.StringTestCase.testReplaceBoundedString() for usage details. + * + * @param initial the String in which we want to replace bounded Strings + * @param prefix the prefix used identify the beginning of the String targeted for replacement + * @param suffix the suffix used to identify the end of the String targeted for replacement + * @param replacement the String to replace the bounded String with + * @param replaceIfBoundedStringEmpty <code>true</code> to allow replacement of empty Strings (in essence, insertion + * of the replacement String between the prefix and suffix) + * @param keepBoundaries <code>true</code> to keep the prefix and suffix markers in the resulting + * String + * @return a String where the Strings marked by prefix and suffix have been replaced by replacement + */ public static String replaceBoundedString(String initial, String prefix, String suffix, String replacement, boolean replaceIfBoundedStringEmpty, boolean keepBoundaries) { @@ -905,13 +922,16 @@ /** * Determines if value is contained in array. + * <p/> + * todo: correct this method contract in order to make it more reusable, it looks like for now like a method which + * has a contract convenient only for some kind of callers. + * <p/> + * <ol> + * <li>null value should be accepted (or the method should be called isContainedInButNotForNullValue ?)</li> + * <li>null array should not be accepted (or the method should be called isContainedInExceptIfThePassedArrayIsNull + * ?)</li> + * </ol> * - * todo: correct this method contract in order to make it more reusable, it looks like for now like a method - * which has a contract convenient only for some kind of callers. - * - * 1/ null value should be accepted (or the method should be called isContainedInButNotForNullValue ?) - * 2/ null array should not be accepted (or the method should be called isContainedInExceptIfThePassedArrayIsNull ?) - * * @param value * @param array * @return @@ -939,13 +959,13 @@ } /** - * Attempt to cast the value argument to the provided type argument. If the value argument type is assignable - * to the provided type, the value is returned, otherwise if it is not or the value is null, null is returned. - * + * Attempt to cast the value argument to the provided type argument. If the value argument type is assignable to the + * provided type, the value is returned, otherwise if it is not or the value is null, null is returned. + * <p/> * todo: Move that to common package. * * @param value the value to cast - * @param type the type to downcast + * @param type the type to downcast * @return the casted value or null */ public static <T> T safeCast(Object value, Class<T> type)