lava.util
Class ResourceLoader

java.lang.Object
  |
  +--lava.util.ResourceLoader

public class ResourceLoader

extends java.lang.Object

Extracts resources from properties file.

Details: ResourceLoader offers a convenient interface for reading various types of objects from a properties file. To use ResourceLoader, construct an instance using the properties file resource name. (Don't begin with a slash and separate path components with forward slashes only, regardless of platform.) Then call any of ResourceLoader's methods to access specific types of objects defined in the properties file.

ResourceLoader maintains an Exception buffer to hold exactly one exception. Whenever an exception occurs, the Exception is caught and stored in the buffer rather than being thrown at the caller. This makes it possible to detect errors while using an interface that returns reasonable defaults when errors occur. Only the first exception to occur will be saved. To detect and capture additional exceptions after one has already been trapped, you must call clearException or getException.

When ResourceLoader is unable to read a requested property, ResourceLoader returns a default value and saves the Exception that occurred according the above-mentioned criteria.

Since:

1999.04.28

Version:

2000.02.10

Author:

Sharky

Field Summary

static boolean

debugging Enables debugging output.

Constructor Summary

ResourceLoader(java.util.PropertyResourceBundle properties)
Sets property resource bundle.

ResourceLoader(java.lang.String resname)
Sets properties file filename.

Method Summary

void	clearException() Clears exception buffer.
boolean	getBoolean(java.lang.String key) Reads a boolean property.
boolean	getBoolean(java.lang.String key, boolean defval) Reads a boolean property.
java.awt.Dimension	getDimension(java.lang.String key) Reads a Dimension property.
double	getDouble(java.lang.String key) Returns a double resource.
double	getDouble(java.lang.String key, double defval) Returns a double resource.
java.lang.Exception	getException() Returns previously saved exception.
java.io.File	getFile(java.lang.String key) Returns File from property.
java.io.File	getFile(java.lang.String key, java.io.File defval) Returns File from property.
float	getFloat(java.lang.String key) Returns a float resource.
float	getFloat(java.lang.String key, float defval) Returns a float resource.
java.net.InetAddress	getHost(java.lang.String key) Returns host address property.
java.net.InetAddress	getHost(java.lang.String key, java.net.InetAddress defval) Returns host address property.
java.net.InetAddress	getHost(java.lang.String key, java.lang.String defval) Returns host address property.
java.io.InputStream	getInputStream(java.lang.String key) Returns an InputStream property.
int	getInt(java.lang.String key) Returns an int resource.
int	getInt(java.lang.String key, int defval) Returns an int resource.
long	getLong(java.lang.String key) Returns a long resource.
long	getLong(java.lang.String key, long defval) Returns a long resource.
java.awt.Point	getPoint(java.lang.String key) Reads a Point property.
java.awt.Rectangle	getRectangle(java.lang.String key) Reads a Rectangle property.
java.lang.String	getString(java.lang.String key) Returns a String resource.
java.lang.String	getString(java.lang.String key, java.lang.String defval) Returns a String resource.
java.lang.String[]	getStringArray(java.lang.String key) Returns string array property.
java.awt.Image	loadImage(java.lang.String key) Returns an Image property.
void	setRedirectionPrefix(java.lang.String rp) No summary available.

Methods inherited from class java.lang.Object

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

Field Detail

debugging

public static boolean debugging

Enables debugging output.

Details: When debugging is set to true, this instance will output information to System.err that may be useful when debugging resource loading problems.

Since:

1999.07.14

Constructor Detail

ResourceLoader

public ResourceLoader(java.util.PropertyResourceBundle properties)

Sets property resource bundle.

Details: This constructor initializes a new instance to read data from the given PropertyResourceBundle. This constructor is not the best way to instantiate ResourceLoaders but is provided for convenience. Where possible, you should let ResourceLoader load the properties file.

Parameters:

properties - the PropertyResourceBundle to read from

ResourceLoader

public ResourceLoader(java.lang.String resname)

Sets properties file filename.

Details: This constructor searchers the classpath for a properties file of the given name, and then uses it to read the requested data. Do not include the ".properties" extension and use only forward slashes to separate package path elements. Do not begin the path with a slash.

Parameters:

resname - the properties file name

Method Detail

getException

public java.lang.Exception getException()

Returns previously saved exception.

Details: getException returns the contents of the exception buffer. A return value of null indicates that no exception has occurred since the last call to getException or clearException. getException automatically clears the exception buffer upon return.

Returns:

the saved Exception

clearException

public void clearException()

Clears exception buffer.

Details: clearException clears the exception buffer. This method is typically called just before loading a resource when a default failure value is unacceptable.

setRedirectionPrefix

public void setRedirectionPrefix(java.lang.String rp)

No summary available.

Details: setRedirectionPrefix sets this ResourceLoader's redirection prefix. The redirection prefix is an optionally definable prefix to propery values that directs the resource loader to optain the property's real value through another key. For example, suppose the following keys were defined:

favorite.fruit=banana
favorite.food=*favorite.fruit

If the redirection prefix is set to "*", then queries for the value of property "favorite.food" will return the value of property "favorite.fruit", which in this case is "banana".

The redirection prefix can be disabled by setting it to null.

Parameters:

rp - the new redirection prefix

Since:

1999

getString

public final java.lang.String getString(java.lang.String key)

Returns a String resource.

Details: getString returns the String associated with the given key. If the String cannot be read, the interned representation of "" is returned. (This means you can compare the return value to "" using == "" instead of .equals("").

Parameters:

key - the key

Returns:

String resource

getString

public final java.lang.String getString(java.lang.String key,
                                        java.lang.String defval)

Returns a String resource.

Details: getString returns the String associated with the given key. If the String cannot be read, the given default string is returned instead.

Parameters:

key - the key

defval - default value

Returns:

String resource

Since:

2000.11.07

getInt

public int getInt(java.lang.String key)

Returns an int resource.

Details: getInt returns the int associated with the given key. 0 is returned if the int cannot be read or parsed.

Parameters:

key - the key

Returns:

the int

getInt

public int getInt(java.lang.String key,
                  int defval)

Returns an int resource.

Details: getInt returns the int associated with the given key. If the int cannot be read or parsed, the given default value (defval) is returned instead.

Parameters:

key - the key

defval - default value

Returns:

the int

Since:

2000.11.07

getLong

public long getLong(java.lang.String key)

Returns a long resource.

Details: getLong returns the long associated with the given key. 0L is returned if the long cannot be read or parsed.

Parameters:

the - key

Returns:

the long

Since:

1999.07.15

getLong

public long getLong(java.lang.String key,
                    long defval)

Returns a long resource.

Details: getLong returns the long associated with the given key. If the long cannot be read or parsed, the given default value (defval) is returned instead.

Parameters:

key - the key

defval - default value

Returns:

the long

Since:

2000.11.07

getDouble

public double getDouble(java.lang.String key)

Returns a double resource.

Details: getDouble returns the double associated with the given key. 0.0 is returned if the double cannot be read or parsed.

Parameters:

the - key

Returns:

the double

Since:

1999.07.15

getDouble

public double getDouble(java.lang.String key,
                        double defval)

Returns a double resource.

Details: getDouble returns the double associated with the given key. If the double cannot be read or parsed, the given default value (defval) is returned instead.

Parameters:

the - key

Returns:

the double

Since:

2000.11.07

getFloat

public float getFloat(java.lang.String key)

Returns a float resource.

Details: getFloat returns the float associated with the given key. 0 is returned if the float cannot be read or parsed.

Parameters:

the - key

Returns:

the float

Since:

1999.07.15

getFloat

public float getFloat(java.lang.String key,
                      float defval)

Returns a float resource.

Details: getFloat returns the float associated with the given key. If the float cannot be read or parsed, the given default value (defval) is returned instead.

Parameters:

the - key

Returns:

the float

Since:

2000.11.07

getDimension

public java.awt.Dimension getDimension(java.lang.String key)

Reads a Dimension property.

Details: getDimension uses getInt to construct a Dimension based on the given key. getDimension appends ".width" and ".height" to the original key and searches using the new keys. The values obtained are then used to construct a new Dimension object, which is returned. If either the width or height cannot be determined, their corresponding members in the returned Dimension object will be set to 0. null will never be returned.

Parameters:

key - the key

Returns:

the Dimension

getPoint

public java.awt.Point getPoint(java.lang.String key)

Reads a Point property.

Details: getPoint uses getInt to construct a Point based on the given key. getPoint appends ".x" and ".y" to the original key and searches using the new keys. The values obtained are then used to construct a new Point object, which is returned. If either the x coordinate or the y coordinate cannot be determined, their corresponding members in the Point object will be set to 0. null will never be returned.

Parameters:

key - the key

Returns:

the Point

getRectangle

public java.awt.Rectangle getRectangle(java.lang.String key)

Reads a Rectangle property.

Details: getRectangle uses getPoint and getDimension to construct a Rectangle from the given key. The Rectangle is returned.

Parameters:

key - the key

Returns:

the Rectangle

getBoolean

public boolean getBoolean(java.lang.String key)

Reads a boolean property.

Details: getBoolean parses the string associated with the given key and attempts to form a boolean value from it. Currently supported boolean representations for true are

true, t, 1, yes, and y.

Supported representations of false are

false, f, 0, no, and n.

If the property is missing or the string cannot be parsed, false is returned as the default value. Use getException to check for errors.

Parameters:

key - the property key

Returns:

the boolean value

getBoolean

public boolean getBoolean(java.lang.String key,
                          boolean defval)

Reads a boolean property.

Details: getBoolean parses the string associated with the given key and attempts to form a boolean value from it. Currently supported boolean representations for true are

true, t, 1, yes, and y.

Supported representations of false are

false, f, 0, no, and n.

If the property is missing or the string cannot be parsed, the given default value (defval) is returned instead. Use getException to check for errors.

Parameters:

key - the property key

Returns:

the boolean value

getFile

public java.io.File getFile(java.lang.String key)

Returns File from property.

Details: getFile returns a File object based on the string obtained from the given key. It is similar to new File(rl.getString(key)), where rl is the ResourceLoader. null is returned if the filename cannot be determined from the properties resource. Otherwise, the new File object is returned.

Parameters:

key - name of filename property

Returns:

the File

getFile

public java.io.File getFile(java.lang.String key,
                            java.io.File defval)

Returns File from property.

Details: getFile returns a File object based on the string obtained from the given key. It is similar to new File(rl.getString(key)), where rl is the ResourceLoader. If the filename cannot be determined from the properties resource, the given default value (defval) is returned instead.

Parameters:

key - name of filename property

Returns:

the File

getHost

public java.net.InetAddress getHost(java.lang.String key)

Returns host address property.

Details: getHost returns an InetAddress based on the value of the named property. If no such property exists, getHost returns "127.0.0.1". If no host cannot be resolved, getHost returns null

Parameters:

key - property key

Returns:

host associated with key

Since:

2000.11.07

getHost

public java.net.InetAddress getHost(java.lang.String key,
                                    java.lang.String defval)

Returns host address property.

Details: getHost returns an InetAddress based on the value of the named property. If no such property exists, getHost returns a host constructed from the given default value (defval). If both the looked up host and the default host cannot be resolved (or is null), getHost returns null.

Parameters:

key - property key

defval - default host

Returns:

host associated with key

Since:

2000.11.07

getHost

public java.net.InetAddress getHost(java.lang.String key,
                                    java.net.InetAddress defval)

Returns host address property.

Details: getHost returns an InetAddress based on the value of the named property. If no such property exists, getHost returns the given default value (defval).

Parameters:

key - property key

defval - default host

Returns:

host associated with key

Since:

2000.11.07

loadImage

public java.awt.Image loadImage(java.lang.String key)

Returns an Image property.

Details: getImage uses getString with the supplied key to find the resource name of an image and then returns an Image object pointing to the image. At this point, there is no guarantee that the image exists, since the AWT does not beginning loading an image until the image's data is actually needed. For more reliability, use ImageLoader. If failure is detected at this step, loadImage returns null.

Parameters:

key - the key

Returns:

the Image

getInputStream

public java.io.InputStream getInputStream(java.lang.String key)

Returns an InputStream property.

Details: getInputStream uses getString with the supplied key to find the resource name of a byte stream and then attempts to load it. If the resource is found and successfully initialized, it is returned. Otherwise, null is returned.

Since:

1999

getStringArray

public java.lang.String[] getStringArray(java.lang.String key)

Returns string array property.

Details: getStringArray returns an array of strings from the properties file. The array's length is determined by calling getInt on the key formed by adding ".length" to the given key (key). Thereafter, individual members of the string array are obtained by calling getString on the keys formed by adding "[0]", "[1]", ... to key, up to but not including the determined length.

Parameters:

key - the name of the array

Returns:

the array