com.partnersoft.data
Class 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.

Version:

$Id: ConversionLib.java 1842 2009-03-25 15:08:25Z rich $

Author:

Paul Reavis, Russell Cagle

Method Summary

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.