ConversionLib

java.lang.Object
- com.partnersoft.data.ConversionLib

All Implemented Interfaces:

Lib
```
public class ConversionLib
extends java.lang.Object
implements Lib
```
Functions for converting simple data from one type to another.
Mostly, this Lib exists to fill in holes in Java's type casting model. Quite often you want to be a little looser with your data than Java likes, such as treating a String as a Number and vice versa. Also, conversions between primitives and their object wrappers (e.g. Integer vs. int) wasn't automated until Java 1.5, and this class handles that problem nicely.
It also deals more elegantly with null values and other frequent problems in data mangling.
There are two major categories of method in this Lib.
Methods with names of the form "convertToFoo" attempt to convert the input value into the output type using a variety of techiques. Nulls are returned as nulls, or may cause a NullPointerException, and invalid inputs (e.g. while trying to parse a number out of a String) will cause an IllegalArgumentException.
Methods with names of the form "forceToFoo" are more aggressive, and will always return a value without throwing an Exception. The value will only be null if the input is null and the output type is a non-primitive Object type. If a problem occurs, or if null input is given, then the returned result will be one of the default constants defined in this class with a name like DEFAULT_FOO.
Copyright 1997-2006 Partner Software, Inc.

Author:

Paul Reavis, Russell Cagle

Method Summary

Methods
Modifier and Type	Method and Description
`static java.lang.Object`	`convert(java.lang.Object value, java.lang.Class convertTo)` A generalized type conversion tool.
`static java.lang.Object`	`convert(java.lang.Object value, java.lang.String className)`
`static java.lang.Number`	`convertNumber(java.lang.Number value, java.lang.Class convertTo)` Attempts to convert a numeric type to another.
`static boolean`	`convertToBoolean(java.lang.Object value)` Converts to a primitive boolean.
`static double`	`convertToDouble(java.lang.Object value)` Converts to a primitive double.
`static float`	`convertToFloat(java.lang.Object value)` Converts to a primitive boolean.
`static int`	`convertToInt(java.lang.Object value)` Converts to a primitive int.
`static long`	`convertToLong(java.lang.Object value)` Converts to a primitive boolean.
`static short`	`convertToShort(java.lang.Object value)` Converts to a primitive short.
`static java.lang.String`	`convertToString(java.lang.Object value)` Converts to a String.
`static java.lang.Object`	`defaultValueFor(java.lang.Class clazz)` Returns a reasonable default value for the given class.
`static java.lang.Object`	`deriveObject(java.lang.Object value, java.lang.Class convertTo)` Derives one object from another by looking for a single-arg constructor of the input type.
`static java.lang.Object`	`force(java.lang.Object value, java.lang.Class convertTo)` A more aggressive conversion tool.
`static java.lang.Object`	`force(java.lang.Object value, java.lang.String className)`
`static boolean`	`forceToBoolean(java.lang.Object value)` Forces to a primitive boolean.
`static double`	`forceToDouble(java.lang.Object value)` Forces to a primitive double.
`static float`	`forceToFloat(java.lang.Object value)` Forces to a primitive boolean.
`static int`	`forceToInt(java.lang.Object value)` Forces to a primitive int.
`static long`	`forceToLong(java.lang.Object value)` Forces to a primitive boolean.
`static short`	`forceToShort(java.lang.Object value)` Forces to a primitive short.
`static java.lang.String`	`forceToString(java.lang.Object value)` Forces to a String.
`static java.lang.Class`	`primitiveClassFor(java.lang.Class wrapperClass)` Returns the primitive class for the given wrapper class.
`static java.lang.Class`	`wrapperClassFor(java.lang.Class primitiveClass)` Returns the wrapper class for the given primitive class.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - wrapperClassFor
```
public static java.lang.Class wrapperClassFor(java.lang.Class primitiveClass)
```
    Returns the wrapper class for the given primitive class. For example, returns the class java.lang.Integer.TYPE if you give it java.lang.Integer.class.
    
    Parameters:
    primitiveClass - Class object representing a Java language primitive.
    
    Returns:
    Corresponding wrapper Class.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the class provided is not a primitive.
  - primitiveClassFor
```
public static java.lang.Class primitiveClassFor(java.lang.Class wrapperClass)
```
    Returns the primitive class for the given wrapper class. For example, returns the class java.lang.Integer.class if you give it java.lang.Integer.TYPE.
    
    Parameters:
    wrapperClass - Class object representing a Java language wrapper.
    
    Returns:
    Corresponding wrapper Class.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the class provided is not a wrapper.
  - defaultValueFor
```
public static java.lang.Object defaultValueFor(java.lang.Class clazz)
```
    Returns a reasonable default value for the given class. In general it will be zero for all numeric types, a blank string for string, an empty array for array types, and null for other types.
    
    Parameters:
    clazz - class we need a default vale for.
    
    Returns:
    default value for the class.
  - convert
```
public static java.lang.Object convert(java.lang.Object value,
                       java.lang.Class convertTo)
```
    A generalized type conversion tool. Does its best to convert a value of one class into a value of another. Makes some assumptions that could be dangerous, but allows the kind of loose typing that is often necessary when moving data back and forth between text files, databases, scripts, and java classes.
    You probably don't need to call this method directly - instead use the more specific convertToFoo() style methods below.
    If the value is already an instance of the convertTo class, simply returns the value.
    If the convertTo class is a primitive, will return an object of the corresponding wrapper class. You'll have to convert it to a primitive yourself.
    If the value or class given is null, then it will generally return null. It can't turn null into a primitive, so it will throw NullPointerException in that case.
    Most magically, IF value is not an instance of the convertTo class, BUT an instance of the convertTo class can be created using a constructor that takes the value's class as its sole parameter, THEN it returns an object created using that constructor and using the given value. Neato! But hold onto your butt!
    
    Parameters:
    value - value to be converted.
    convertTo - class value is to be converted to.
    
    Returns:
    converted value; null if the value or class given are null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the coercion isn't possible.
  - convert
```
public static java.lang.Object convert(java.lang.Object value,
                       java.lang.String className)
```
  - force
```
public static java.lang.Object force(java.lang.Object value,
                     java.lang.String className)
```
  - force
```
public static java.lang.Object force(java.lang.Object value,
                     java.lang.Class convertTo)
```
    A more aggressive conversion tool.
    This method does everything that convert(Object, Class) does and more. Specifically, it does its best to cram one type into the other, and if it can't, it returns a default value rather than throw an exception.
    This can be dangerous, which is why we named it "force". For example, if you try to convert the String "135-1" into a number, you'll get the number zero (0). Not exactly what you might have expected.
    However, there are times when you just want to pull the data in, and don't really care about dropping invalid values, and you don't want to fill up the log with warnings. This function is for those times.
    
    Parameters:
    value - value to be converted.
    convertTo - class value is to be converted to.
    
    Returns:
    converted value; null if the value or class given are null, and a default value from DataConstants if it can't convert it for some reason.
  - convertNumber
```
public static java.lang.Number convertNumber(java.lang.Number value,
                             java.lang.Class convertTo)
```
    Attempts to convert a numeric type to another. Can result in loss of data or precision, so be careful!
    
    Parameters:
    value - value to be converted.
    convertTo - class value is to be converted to.
    
    Throws:
    
    java.lang.IllegalArgumentException - if convertTo isn't a numeric class.
  - deriveObject
```
public static java.lang.Object deriveObject(java.lang.Object value,
                            java.lang.Class convertTo)
```
    Derives one object from another by looking for a single-arg constructor of the input type.
    This is deep, potentially fey magic.
    If anything goes wrong, throws an IllegalArgumentException.
    
    Parameters:
    value - value to be converted.
    convertTo - class value is to be converted to.
    
    Returns:
    converted value.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - convertToBoolean
```
public static boolean convertToBoolean(java.lang.Object value)
```
    Converts to a primitive boolean.
    
    Parameters:
    value - value to be converted.
    
    Returns:
    converted value; false if input is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - convertToShort
```
public static short convertToShort(java.lang.Object value)
```
    Converts to a primitive short.
    
    Parameters:
    value - value to be converted.
    
    Returns:
    converted value, 0 if input is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - convertToInt
```
public static int convertToInt(java.lang.Object value)
```
    Converts to a primitive int.
    
    Parameters:
    value - value to be converted.
    
    Returns:
    converted value, 0 if input is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - convertToLong
```
public static long convertToLong(java.lang.Object value)
```
    Converts to a primitive boolean.
    
    Parameters:
    value - value to be converted.
    
    Returns:
    converted value; false if input is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - convertToFloat
```
public static float convertToFloat(java.lang.Object value)
```
    Converts to a primitive boolean.
    
    Parameters:
    value - value to be converted.
    
    Returns:
    converted value; false if input is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - convertToDouble
```
public static double convertToDouble(java.lang.Object value)
```
    Converts to a primitive double.
    
    Parameters:
    value - value to be converted.
    
    Returns:
    converted value; zero if input is null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - convertToString
```
public static java.lang.String convertToString(java.lang.Object value)
```
    Converts to a String.
    
    Parameters:
    value - value to be converted
    
    Returns:
    converted value; null if input is null
    
    Throws:
    
    java.lang.IllegalArgumentException - if the conversion fails.
  - forceToBoolean
```
public static boolean forceToBoolean(java.lang.Object value)
```
    Forces to a primitive boolean.
    
    Parameters:
    value - value to be forced.
    
    Returns:
    forced value; false if input is null.
  - forceToShort
```
public static short forceToShort(java.lang.Object value)
```
    Forces to a primitive short.
    
    Parameters:
    value - value to be forced.
    
    Returns:
    forced value, 0 if input is null.
  - forceToInt
```
public static int forceToInt(java.lang.Object value)
```
    Forces to a primitive int.
    
    Parameters:
    value - value to be forced.
    
    Returns:
    forced value, 0 if input is null.
  - forceToLong
```
public static long forceToLong(java.lang.Object value)
```
    Forces to a primitive boolean.
    
    Parameters:
    value - value to be forced.
    
    Returns:
    forced value; 0 if input is null.
  - forceToFloat
```
public static float forceToFloat(java.lang.Object value)
```
    Forces to a primitive boolean.
    
    Parameters:
    value - value to be forced.
    
    Returns:
    forced value; 0 if input is null.
  - forceToDouble
```
public static double forceToDouble(java.lang.Object value)
```
    Forces to a primitive double.
    
    Parameters:
    value - value to be forced.
    
    Returns:
    forced value; 0 if input is null.
  - forceToString
```
public static java.lang.String forceToString(java.lang.Object value)
```
    Forces to a String.
    
    Parameters:
    value - value to be forced.
    
    Returns:
    forced value; "" if input is null.

Class ConversionLib

Method Summary

Methods inherited from class java.lang.Object

Method Detail

wrapperClassFor

primitiveClassFor

defaultValueFor

convert

convert

force

force

convertNumber

deriveObject

convertToBoolean

convertToShort

convertToInt

convertToLong

convertToFloat

convertToDouble

convertToString

forceToBoolean

forceToShort

forceToInt

forceToLong

forceToFloat

forceToDouble

forceToString