ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.util
Class StringConvert

java.lang.Object
  extended by umontreal.iro.lecuyer.util.StringConvert

public class StringConvert
extends Object

Provides utility methods to convert strings into Java objects. The Java class library already contains some facilities to convert strings to many object types, but the target class must be known at compile time. With these utility methods, a conversion can be performed with a target class known at run time.


Method Summary
static Boolean booleanFromString(String val)
          Converts a string val to a boolean wrapper object.
static String byteToString(byte b)
          Same as intToString(int) for a byte.
static Duration durationFromString(String str)
          Constructs and returns a Duration object obtained from the string str.
static
<T> T
fromString(URI baseURI, ClassFinder finder, Class<T> cls, String val)
          Tries to convert the string val into an object of the class cls or one of its subclasses or implementations.
static Object[] getArgumentsFromString(URI baseURI, ClassFinder finder, Class<?>[] paramTypes, String[] vals)
          Converts an array of strings vals to an array of arguments to be passed to a constructor or method with parameter types paramTypes.
static String[] getArrayElements(String val)
          Tokenizes the string val into an array of strings using whitespaces or commas as delimiters, and merging back parts surrounded by braces or parentheses.
static
<T> T
getStaticValue(URI baseURI, ClassFinder finder, Class<T> cls, String val)
          Converts val to an instance of cls by considering the string as a call to a constructor, a static method or a static field.
static String intToString(int i)
          Converts the integer value i to a string by using String.valueOf(int).
static String longToString(long l)
          Same as intToString(int) for a long.
static
<T> T
numberFromString(Class<T> cls, String val)
          Converts the string val to an instance of cls being a subclass of Number or a primitive numeric type.
static String numberToString(Number n)
          Formats the number n into a string.
static String shortToString(short s)
          Same as intToString(int) for a short.
static
<T> T
tryToCallConstructor(URI baseURI, ClassFinder finder, Class<T> cls, String... vals)
          Tries to find a compatible constructor in class cls, converts the arguments stored into vals to the arguments of the constructor, calls it and returns the constructed instance.
static
<T> T
tryToCallMethod(URI baseURI, ClassFinder finder, Class<T> rcls, Class<?> cls, Object o, String name, String... vals)
          Tries to call a method named name on object o with arguments given by vals, with expected return value class rcls.
static URI uriFromString(URI baseURI, String uri)
          Constructs and returns a new URI from the string url, resolved against the base URI baseURI.
static URL urlFromString(URI baseURI, String url)
          This method calls uriFromString(URI,String) with the given base URI, and URL, and converts the resulting URI into a URL using URI.toURL().
static
<T> T
wrapperFromString(Class<T> cls, String val)
          Converts a string to a wrapper object of class cls.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

fromString

public static <T> T fromString(URI baseURI,
                               ClassFinder finder,
                               Class<T> cls,
                               String val)
                    throws UnsupportedConversionException,
                           NameConflictException
Tries to convert the string val into an object of the class cls or one of its subclasses or implementations. cls can be a primitive type, a class type, or an array. When a primitive target type is given, the method returns an object from the corresponding wrapper class. The class finder finder is used to resolve class names and will be replaced by Class.forName(java.lang.String) if null.

If cls is String or Object, val is returned unchanged. If it is null, a null pointer is returned. The method tries to use numberFromString(Class,String) for numeric types. If cls corresponds to the Duration class, this method calls durationFromString(String). If cls.isEnum() returns true, it uses Enum.valueOf(java.lang.Class, java.lang.String) to convert the string to an object representing an enum constant. For the char type, the first character of the string is returned into the Character wrapper object. For boolean type, the method uses booleanFromString(String). Objects of class URI are obtained using uriFromString(URI,String) while objects of class URL are obtained by urlFromString(URI,String). If no previous class is compatible with the target class, the method tries to use wrapperFromString(Class,String) to perform the conversion.

If the target object is from class Class, the given string is interpreted as a class name and passed to findClass to get a Class object, using the class finder to resolve the class name. If finder is null, Class.forName(java.lang.String) is used instead.

The method also processes arrays in arbitrary depths. For a one-dimensional array, the string is read as a list of tokens separated with commas and for each token, the method is called recursively. The getArrayElements(java.lang.String) method is used to perform the tokenization. To encode multi-dimensional arrays, one must encode arrays into tokens by using the brackets. For example, if the target class is int[][], [1,2],[3,4] will be converted as a 2D array with 1,2 in the index 0 and 3,4 in the index 1.

If the target class is not an array and cannot be converted in any ways, the method forwards the call to getStaticValue(java.net.URI, umontreal.iro.lecuyer.util.ClassFinder, java.lang.Class, java.lang.String).

Parameters:
baseURI - the base URI used by uriFromString(URI,String) and urlFromString(URI,String).
finder - the class finder being used to look for classes if necessary.
cls - the target class of the returned object.
val - the string to be converted.
Returns:
the converted object.
Throws:
IllegalArgumentException - if the string cannot be converted, although conversion to the target class is supported.
UnsupportedConversionException - if the target class is not supported by the converter.
NameConflictException - if a name conflict occurs when resolving a class name.

getArgumentsFromString

public static Object[] getArgumentsFromString(URI baseURI,
                                              ClassFinder finder,
                                              Class<?>[] paramTypes,
                                              String[] vals)
                                       throws UnsupportedConversionException,
                                              NameConflictException
Converts an array of strings vals to an array of arguments to be passed to a constructor or method with parameter types paramTypes. The method tries to convert vals[p] to the class given by paramTypes[p] using the String) method and stores the result in the returned array.

Parameters:
baseURI - the base URI used by fromString(URI,ClassFinder,Class,String)
paramTypes - the target type of each argument.
vals - the string arguments.
Returns:
an array of objects representing each argument.
Throws:
IllegalArgumentException - if vals and paramTypes have different lengths or a conversion error occurred.
NullPointerException - if vals, paramTypes or any elements of these arrays are null.
UnsupportedConversionException - if the converter does not support one or more argument class.
NameConflictException

getStaticValue

public static <T> T getStaticValue(URI baseURI,
                                   ClassFinder finder,
                                   Class<T> cls,
                                   String val)
                        throws UnsupportedConversionException,
                               NameConflictException
Converts val to an instance of cls by considering the string as a call to a constructor, a static method or a static field. The string must be speficied as a Java expression. The arguments of constructors and static methods are processed by String). The constructed class, the type of the static field, or the return value of the static method must be assignable to the target class. If the conversion fails, an IllegalArgumentException is thrown.

Parameters:
baseURI - the base URI used by uriFromString(URI,String) and urlFromString(URI,String).
finder - the class finder being used.
cls - the target class for the conversion.
val - the expression being converted.
Returns:
the constructed object.
Throws:
UnsupportedConversionException - if String) fails processing the arguments because the class of the called constructor's arguments, the type of the referenced field, or the return value of the called method are not supported as target classes.
NameConflictException - if a class name conflict arises.
IllegalArgumentException - if the target class is supported but a conversion problem occurs.

getArrayElements

public static String[] getArrayElements(String val)
Tokenizes the string val into an array of strings using whitespaces or commas as delimiters, and merging back parts surrounded by braces or parentheses. Parentheses always appear in resulting tokens while the surrounding braces are removed. Any consecutive substring of whitespace is replaced by a single whitespace character. This method is different from String.split(java.lang.String, int) because it takes braces and parentheses into account.

For example, the string 1 2 3 4 given to this method would produce an array containing four elements: 1, 2, 3, and 4. The string {1,2} {3 4} will be separated in two strings by this method: 1 2 and 3 4. The string {{1 2} 3} a (4 5) would become an array containing { 1 2 } 3, and a ( 4 5 ).

Parameters:
val - the value to be tokenized.
Returns:
an array of strings representing each token.

numberFromString

public static <T> T numberFromString(Class<T> cls,
                                     String val)
                          throws UnsupportedConversionException
Converts the string val to an instance of cls being a subclass of Number or a primitive numeric type. In the val argument, the method accepts a number or the special strings Infinity, INF, -Infinity, and -INF. For an integer, a short, a long or a byte, infinity is represented using the greatest or smallest acceptable value for the built-in types. For single or double-precision floating points, the infinity can be represented directly. For floating-points, the nan string is accepted to denote a NaN.

Parameters:
cls - the target class.
val - the string being converted.
Returns:
the constructed numeric wrapper object.
Throws:
NumberFormatException - if a conversion problem occurred.
UnsupportedConversionException - if the class is not a supported subclass of Number or a primitive numeric type.

booleanFromString

public static Boolean booleanFromString(String val)
Converts a string val to a boolean wrapper object. The method accepts 1, true, yes, and on as a true value and 0, false, no, and off as a false value.

Parameters:
val - the value being converted.
Returns:
the result of the conversion.
Throws:
IllegalArgumentException - if the value cannot be converted.

uriFromString

public static URI uriFromString(URI baseURI,
                                String uri)
Constructs and returns a new URI from the string url, resolved against the base URI baseURI. If baseURI is null, this method creates a new URI using the URI.URI(String) constructor. Otherwise, it resolves the string uri against the base URI to obtain the URI object. Any exception is wrapped into an illegal-argument exception.

Parameters:
baseURI - the base URI.
uri - the URI to resolve.
Returns:
the resolved URI object.

urlFromString

public static URL urlFromString(URI baseURI,
                                String url)
This method calls uriFromString(URI,String) with the given base URI, and URL, and converts the resulting URI into a URL using URI.toURL().

Parameters:
baseURI - the base URI.
url - the URL.
Returns:
the resulting URL object.

durationFromString

public static Duration durationFromString(String str)
                                   throws UnsupportedConversionException
Constructs and returns a Duration object obtained from the string str. This method uses DatatypeFactory.newDuration(String) to perform the conversion.

Parameters:
str - the string to convert.
Returns:
the obtained duration.
Throws:
UnsupportedConversionException - if the data type factory could not be created.

wrapperFromString

public static <T> T wrapperFromString(Class<T> cls,
                                      String val)
                           throws UnsupportedConversionException
Converts a string to a wrapper object of class cls. This method tries to find a constructor for class cls taking a String as its unique argument. If such a constructor can be found, it is used to instantiate a new object which is returned. If no such constructor can be found and invoked, the method searches for a valueOf public static method taking a String argument and returning an instance of cls or a subclass of cls. If the class does not contain an appropriate constructor or static method, an UnsupportedConversionException is thrown. If the constructor or method is found but cannot be called successfully, an IllegalArgumentException is thrown.

Parameters:
cls - the target class for the conversion.
val - the value being converted.
Returns:
the converted value.
Throws:
IllegalArgumentException - if an exception occurred during the construction of the wrapper object.
UnsupportedConversionException - if the target class does not contain an appropriate constructor or static method.

tryToCallConstructor

public static <T> T tryToCallConstructor(URI baseURI,
                                         ClassFinder finder,
                                         Class<T> cls,
                                         String... vals)
                              throws UnsupportedConversionException,
                                     NameConflictException,
                                     NoSuchMethodException
Tries to find a compatible constructor in class cls, converts the arguments stored into vals to the arguments of the constructor, calls it and returns the constructed instance. For each constructor with the appropriate number of arguments, argument vals[i] is converted to the type of the argument i of the constructor, using String[]). If one conversion fails, the other constructors are tried. If all conversion fail, an exception is thrown.

Parameters:
baseURI - the base URI used by uriFromString(URI,String) and urlFromString(URI,String).
finder - the class finder used by String[]).
cls - the target class.
vals - the arguments for the constructor.
Returns:
the constructed instance.
Throws:
UnsupportedConversionException - if some arguments could not be converted.
NameConflictException - if a name conflict occurred during class name resolving.
IllegalArgumentException - if the conversion of an argument is supported by String), but some errors occurred, or an exception occurred during the call to the constructor.
NoSuchMethodException - if no appropriate constructor could be found.

tryToCallMethod

public static <T> T tryToCallMethod(URI baseURI,
                                    ClassFinder finder,
                                    Class<T> rcls,
                                    Class<?> cls,
                                    Object o,
                                    String name,
                                    String... vals)
                         throws UnsupportedConversionException,
                                NameConflictException,
                                NoSuchMethodException
Tries to call a method named name on object o with arguments given by vals, with expected return value class rcls. The method searches for all public methods in cls taking vals.length arguments (0 argument if vals is null), and tries to convert the arguments using String[]). If o is null, the search will be restricted to static methods.

Parameters:
baseURI - the base URI used by uriFromString(URI,String) and urlFromString(URI,String).
finder - the class finder used by String[]).
rcls - the target class of the return type.
cls - the class defining the method to be invoked.
o - the object on which the method is invoked, should be an instance of the class represented by cls.
name - the name of the method.
vals - the arguments for the method.
Returns:
the return value.
Throws:
UnsupportedConversionException - if some arguments are not compatible with String).
NameConflictException - if a name conflict occurs during a class name resolution.
IllegalArgumentException - if no method can be found or some conversions failed.
NoSuchMethodException - if no appropriate method could be found.

intToString

public static String intToString(int i)
Converts the integer value i to a string by using String.valueOf(int). If i is equal to the minimum or maximum value of an integer, -Infinity or Infinity are returned, respectively.

Parameters:
i - the integer being formatted.
Returns:
the formatted integer.

byteToString

public static String byteToString(byte b)
Same as intToString(int) for a byte.

Parameters:
b - the byte being formatted.
Returns:
the formatted byte.

shortToString

public static String shortToString(short s)
Same as intToString(int) for a short.

Parameters:
s - the short integer being formatted.
Returns:
the formatted value.

longToString

public static String longToString(long l)
Same as intToString(int) for a long.

Parameters:
l - the long integer being formatted.
Returns:
the formatted value.

numberToString

public static String numberToString(Number n)
Formats the number n into a string. If n is an instance of wrapped primitive numeric type, the appropriate convert static method of this class is called to perform the conversion. Otherwise, Object.toString() is used. This method is used to return Infinity, and NaN as required, instead of large or small values.

Parameters:
n - the number being formatted.
Returns:
the formatted value.

ContactCenters
V. 0.9.9.

To submit a bug or ask questions, send an e-mail to Richard Simard.