com.ccg.util
Class Convert

java.lang.Object
  com.ccg.util.Convert

Direct Known Subclasses:

ImageGen, TagLookup

public class Convert
extends Object

General purpose string to object convertor. It seems like you are always running into a condition where you need to convert string values into some sort of java object. These string values might come from command line arguments, applet parameters, property files, etc. This class serves as a general work horse of converting string values into Java equivalents.

Once created, you can use this object to conver strings. The conversion of strings to their other representations is isolated here in this class.

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

TagLookup

Constructor Summary

Convert()

Method Summary

static int	choiceValue(String val, String[] choices) Lookup a "choice" from a set of string values.
DateFormat	getDateFormat() Get the date parsing object.
NumberFormat	getNumberFormat() Get the date parsing object.
void	setDateFormat(DateFormat val) Set the date parsing object.
void	setNumberFormat(NumberFormat val) Set the date parsing object.
Boolean	toBoolean(String bs, Boolean def) Take a String and convert it to a Boolean.
Color	toColor(String from, Color dc) Take a String and convert it to a Color.
Date	toDate(String val, Date def) Take a String and convert it to a Date.
Font	toFont(String from, Font df) Take a String and convert it to a Font.
InputStream	toInputStream(String name, InputStream def, boolean allowSystemIn) Convert a string into a InputStream.
Locale	toLocale(String from, Locale df) Get a Locale from a specified string.
Number	toNumber(String val, Number def) Take a String and convert it to a Number.
OutputStream	toOutputStream(String name, OutputStream def, boolean allowSystem, boolean noModify, boolean appendIfFound) Convert a string into a OutputStream.
String	toString(String val, String defaultVal) A simple null and zero length check of a string.
TimeSpan	toTimeSpan(String sval, String eval, TimeSpan def) Convert two strings containing date/time info to a TimeSpan.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Convert

public Convert()

Method Detail

toString

public String toString(String val,
                       String defaultVal)

A simple null and zero length check of a string. This method verifies that the first string passed is not null or zero length. If it falls into one of these conditions, then the default value is returned.

Parameters:

val - Value to check (null is handled).

default - Default value to return (this can be null if desired).

Returns:

The original 'val' if it was non null and at least one character long, 'default' otherwise.

Since:

1.0

See Also:

toNumber(String,Number)

toNumber

public final Number toNumber(String val,
                             Number def)
                      throws ParseException

Take a String and convert it to a Number. This method takes a string and attempts to convert it to a standard Number object. If unable to do so, then the default value you specify (which can be null) will be returned.

Parameters:

val - String to convert (can be null - in which case the default value is retured).

default - Default value to return if value is null (this can be null).

Returns:

Number object as a result of converting the string (or the default value if the string object was null).

Throws:

ParseException - If value is specified but fails to convert properly (since a value was specified, we don't want to return the default, but we do want to let you know about the problem)

Since:

1.0

toBoolean

public final Boolean toBoolean(String bs,
                               Boolean def)
                        throws ParseException

Take a String and convert it to a Boolean.

This method takes a string and attempts to convert it to a standard Boolean object. If unable to do so, then the default value you specify (which can be null) will be returned.

Case is not significant in the conversion. However, we are currently pretty strict about how we interpret the values you pass. The following table shows what you get back based upon the string passed:

String	Result
"true"	Boolean.TRUE
""	Boolean.TRUE
"false"	Boolean.FALSE
null	Default value passed.

Parameters:

val - String to convert (can be null - in which case the default value is retured).

default - Default value to return if 'val' is null (this can be null).

Returns:

Boolean object from the lookup table, or your default value.

Throws:

ParseException - If value is specified but fails to convert properly (since a value was specified, we don't want to return the default, but we do want to let you know about the problem)

Since:

1.0

See Also:

toNumber(String,Number)

toDate

public final Date toDate(String val,
                         Date def)
                  throws ParseException

Take a String and convert it to a Date. This method takes a string and attempts to convert it to a standard Date object. If unable to do so, then the default value you specify (which can be null) will be returned.

Parameters:

val - String to convert (can be null - in which case the default value is retured).

default - Default value to return if 'val' is null (this can be null).

Returns:

Date object from the lookup table, or your default value.

Throws:

ParseException - If value is specified but fails to convert properly (since a value was specified, we don't want to return the default, but we do want to let you know about the problem)

Since:

1.0

See Also:

setDateFormat(java.text.DateFormat)

toTimeSpan

public final TimeSpan toTimeSpan(String sval,
                                 String eval,
                                 TimeSpan def)
                          throws ParseException

Convert two strings containing date/time info to a TimeSpan. This method looks at two string values and attempts to convert them into a TimeSpan object (you use this method if you allow a time span to be specified). If unable to do so, then the default value you specify (which can be null) will be returned. The date parser currently associated for the object will be used to parse the dates.

Note it is considered valid to specify either the start or end time (or both). If just the end time is omitted, it will default to the current time. If just the start time is omitted, it will default to a time way in the past.

Parameters:

start - String to convert of the start time (can be null as described above).

end - String to convert of the end time (can be null as described above)

default - Default TimeSpan to return if both values are missing or one is not valid (this can be null).

Returns:

TimeSpan object parsed from the lookup table, or your default value.

Throws:

ParseException - If value is specified but fails to convert properly (since a value was specified, we don't want to return the default, but we do want to let you know about the problem)

Since:

1.0

See Also:

setDateFormat(java.text.DateFormat)

toInputStream

public InputStream toInputStream(String name,
                                 InputStream def,
                                 boolean allowSystemIn)
                          throws IOException

Convert a string into a InputStream. This method attempts to provide a flexible mechanism to open a InputStream. If a non-null string value is passed, then Utility.getInputStream(String) will be used to convert the String into a InputStream. If that fails, then your default value will be returned.

Parameters:

val - String to convert (can be null - in which case the default value is retured).

def - Default InputStream to return if we are unable to create one from the our lookup. Most likely you will pass null for this parameter (which allows you to detect when the input was omitted or incorrectly specified).

allowSystemIn - Set to true if you want to allow this method to return System.in if the value specified corresponds to "-".

Returns:

A InputStream object. It may be null, if our attempt to open the stream failed and you supplied null as the default return value.

Throws:

IOException - If a non-default value was found in the lookup (corresponding to the 'key') table and could not be converted to a InputStream.

Since:

1.0

See Also:

toString(java.lang.String, java.lang.String)

toOutputStream

public OutputStream toOutputStream(String name,
                                   OutputStream def,
                                   boolean allowSystem,
                                   boolean noModify,
                                   boolean appendIfFound)
                            throws IOException

Convert a string into a OutputStream. This method attempts to provide a flexible mechanism to open a OutputStream. If a non-null string value is passed, then it will be processed as described below to produce a OutputStream. If that fails, then your default value will be returned.

Here are the strings recognized and how they are interpreted:

"-","out"=System.out

If you've specified you want to allow the use of System.out and the lookup value is "-" or "out", then System.out will be returned.

"err"=System.err

If you've specified you want to allow the use of System.err and the lookup value is "err", then System.err will be returned.

File Name

Finally, we will interpret the string as the actual file name which to open via the FileOutputStream class.

Default

Finally, if all attempts fail, we will give up and return your supplied default value.

Parameters:

val - String to convert (can be null - in which case the default value is retured).

def - Default OutputStream to return if we are unable to create one from the our lookup. Most likely you will pass null for this parameter (which allows you to detect when the output was omitted or incorrectly specified).

allowSystem - Set to true if you want to allow this method to return System.out or System.err if the value specified corresponds to "-", "out" or "err".

noModify - Set to true if we should reject any existing file (prevent the modification of existing files).

allowAppend - Set to true if you want the output stream appended to any existing file found, set to false if you just want to overwrite an existing file which has the same name. This parameter is only looked at if 'noModify' is set false.

Returns:

A OutputStream object. It may be null, if our attempt to open the stream failed and you supplied null as the default return value.

Throws:

IOException - If a non-default value was found in the lookup (corresponding to the 'key') table and could not be converted to a OutputStream.

Since:

1.0

See Also:

toString(java.lang.String, java.lang.String)

toColor

public Color toColor(String from,
                     Color dc)
              throws ParseException

Take a String and convert it to a Color. This method takes a string and attempts to convert it to a standard Color object. If unable to do so, then the default value you specify (which can be null) will be returned. The default number parser for the default locale will be used. Colors may be specified as integers (hex works well for this using 0xRRGGBB - where RR is two hex digits 00-ff for red component, GG is two hex digits for green component, and BB is two hex digits for blue component), or by a simple name. The following simple names are recognized:

"black", "blue", "cyan", "darkgray", "gray", "green", "lightgray", "magenta", "orange", "pink", "red", "white", "yellow"

Parameters:

val - String to convert (can be null or zero length - in which case the default value is returned).

default - Default value to return if value is missing or not a valid number (this can be null).

Returns:

Color object from the lookup table, or your default value.

Throws:

ParseException - If value is specified but fails to convert properly (since a value was specified, we don't want to return the default, but we do want to let you know about the problem)

Since:

1.0

See Also:

toFont(String,Font)

toFont

public Font toFont(String from,
                   Font df)
            throws ParseException

Take a String and convert it to a Font. This method takes a string and attempts to convert it to a standard Font object. If unable to do so, then the default value you specify (which can be null) will be returned. The Font.decode(java.lang.String) method is used to decode the string specified. Refer to Font.decode(java.lang.String) for details on forming font names. Here are some valid examples (that should work on all platforms):

• "SansSerif-bold-20"
• "Serif-italic-16"
• "Monospaced-plain-12"
• "Dialog-bolditalic-18"
• "DialogInput-bold-22"

Parameters:

val - String to convert (can be null - in which case the default value is retured).

default - Default value to return if value is missing or not a valid font (this can be null).

Returns:

Font object from the lookup table, or your default value.

Throws:

ParseException - If value is specified but fails to convert properly (since a value was specified, we don't want to return the default, but we do want to let you know about the problem)

Since:

1.0

See Also:

toColor(String,Color)

toLocale

public Locale toLocale(String from,
                       Locale df)
                throws ParseException

Get a Locale from a specified string. This method is intended to convert a string value to a standard Locale object. The strings must be in the form:

ll[_CC[_VARIANT]

ll

This two letter identifier must be the two character language identifier as required by the Locale class. We will force it to lower case (that is we aren't case sensitive) as required by the Locale class. If "ll" isn't exactly two characters, we will throw a parse exception.

_CC

If the language has a specific country code to distinguish its language, you can provide it here. We will force the two character identifier to upper case as required by the Locale class. If "CC" is not exactly two characters, we will throw a ParseException.

_VARIANT

Some locale's permit localization beyond the country code. You can append this value if required. This is fairly vendor specific and no case translation is done (or length check).

To see what locale's are available, try running the following:

 java com.ccg.applet.AppletJVM
 

If you scroll down the window, you should see a list of locale values supported by your JVM environment. It should look something like:

 ...
 #
 # Info from: java.util.Locale
 #
 Default Locale:en_US
 Available:
   en
   en_US
   ar
   ar_AE
   ar_BH
   ar_DZ
 ...
   de_LU_EURO
 ...
 

In addition, you can look at the source code for TagLookupEx.java which demonstrates how one might use this method. If you compile this class, you can also use it from the command line to test out the parsing of locale strings. Invoke it something like:

 java TagLookupEx -local en_US
 java TagLookupEx -local nl
 java TagLookupEx -local de_nl_euro
 

Parameters:

val - String to convert (can be null - in which case the default value is retured).

default - Default value to return if value is not found (this can be null).

Returns:

Locale object which we looked up, or your default value if one wasn't found.

Throws:

ParseException - If value is specified but fails to convert properly (since a value was specified, we don't want to return the default, but we do want to let you know about the problem)

Since:

1.0

See Also:

Locale

choiceValue

public static int choiceValue(String val,
                              String[] choices)

Lookup a "choice" from a set of string values.

This static method takes a string "value" and looks for the index in a list of valid "choices" which you supplied. The results will be one of the following:

>= 0

If the value specified choices matches any of the values specified in the list, the index of the first match is returned.

-1

If a value specified was not null and didn't match any of the valid choices.

-2

If the value passed was null.

-3

If you passed a null "choice" array.

Here's a quick example of how one might use this method:

 public static void foo(String val) {
   String[] modes = { "verbose", "quiet" };
   int mode = TagLookup.choiceValue(val,modes);
                                // if "mode" specified, go set
   if (mode >= 0) setNewMode(mode);
 }
 

Parameters:

val - The value to determine the choice index of. (if you pass null you will get -2 returned).

choices - String array of valid values recognized (if you pass null, you will get -3 returned to you).

Returns:

Index in "choices" array of value specifed, OR a value less than 0 if valid value was not specified. The following reject (negative) values can be returned: -1 - value specified by user but not a valid choice, -2 - value was null, -3 - choices options set to null.

Since:

1.0

setDateFormat

public void setDateFormat(DateFormat val)

Set the date parsing object.

Parameters:

val - New DateFormat value to assign.

See Also:

getDateFormat()

getDateFormat

public DateFormat getDateFormat()

Get the date parsing object.

This method never returns null. If the date parser has never been set (or set to a null object), a new default parser will be created and returned.

Returns:

Current DateFormat value assigned.

See Also:

setDateFormat(java.text.DateFormat)

setNumberFormat

public void setNumberFormat(NumberFormat val)

Set the date parsing object.

Parameters:

val - New NumberFormat value to assign.

See Also:

getNumberFormat()

getNumberFormat

public NumberFormat getNumberFormat()

Get the date parsing object.

This method never returns null. If the date parser has never been set (or set to a null object), a new default parser will be created and returned.

Returns:

Current NumberFormat value assigned.

See Also:

setNumberFormat(java.text.NumberFormat)