com.ccg.io
Class ConfigSource

java.lang.Object
  com.ccg.io.ConfigSource

public class ConfigSource
extends Object

Base class for the purpose of opening configuration files.

For an general overview of configuration issues (and how this class fits in to the scheme), refer to the Configuration Files document.

This class provides the foundation for consistently opening and closing configuration file(s). In provides the mechanisms to open up various input and output forms for the purpose of loading and saving configuration infromation.

The package and class information is used in forming the location of the configuration file in a manner that it is very unlikely that one will have naming conflicts. For example, if you create the classes: com.ccg.run.Main and com.ccg.wp.Main then this class can be used to keep their respective configuration files isolated from one another. Their associated configuration files will be found via:

 $HOME/.etc/com/ccg/run/*.Main
 $HOME/.etc/com/ccg/wp/*.Main
 

The package name and class name are used in combination with the user's home directory (as reported by the JVM) as to where the final location of the configuration files will be located at. So, if you use packages (as you should), and you don't have any name conflicts, then you won't have any configuration conflicts either.

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

getFile()

Constructor Summary

ConfigSource(Class cl)
Constructor which associates a ConfigSource with a class.

Method Summary

ObjectOutputStream	createObjectOutputStream() Attempts to open a ObjectOutputStream for the purpose of saving.
OutputStream	createOutputStream() Attempts to open a OutputStream for the purpose of saving.
PrintWriter	createPrintWriter() Attempts to open a PrintWriter for the purpose of saving.
String[]	getAvailableConfigs() Get list of available configurations.
String	getClassName() Get the full package.class name to identify these configuration objects.
File	getFile() Get's file representation of where the configuration is located at.
String	getSourceName() Get the source name of the configuration file.
Object	loadObject() Load a single Object as entire configuration.
LookupProperties	loadProperties() Loads the set of properties which had been previously saved.
InputStream	openInputStream() Attempts to open a InputStream for the purpose of reading.
LineNumberReader	openLineNumberReader() Attempts to open a LineNumberReader for the purpose of reading.
ObjectInputStream	openObjectInputStream() Attempts to open a ObjectInputStream for the purpose of reading.
void	removeConfig() Remove the configuration from existance.
void	saveObject(Object object) Save single Object as entire configuration.
void	saveProperties(Properties props) Saves the set of properties specified in a manner that they can be loaded in the future.
void	setClassName(String val) Set the full package.class name to identify these configuration objects.
void	setSourceName(String val) Set the source name of the configuration file.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConfigSource

public ConfigSource(Class cl)

Constructor which associates a ConfigSource with a class.

This is the way in which you construct this object. You associate a unique class at the time of construction. The full class name (including package) information is used to differentiate the configuration files created/read from configuration files created for other classes.

Parameters:

cl - The class to associate with the configuration files (must not be null).

Since:

1.0

See Also:

getClassName()

Method Detail

setClassName

public void setClassName(String val)

Set the full package.class name to identify these configuration objects.

If you derive your own ConfigSource object from this class, then you won't need to specify a class name here.

If you are being lazy (or want to reduce the number of classes required for a applet), you can skip the formal step of extending this class. Instead, you can associate a class name with it instead.

The value of the class name affects the form of the configuration files (both directory and extension). For example, if you were to set the class name to "com.ccg.net.URLCat", this would result in the default configuration file being found at "$HOME/.etc/com/ccg/net/default.URLCat".

NOTE: This method may disappear in the future, I'm thinking that I should not allow one to change this on the fly.

Parameters:

val - New String value to assign (if you pass null - we will ignore it).

See Also:

getClassName()

getClassName

public String getClassName()

Get the full package.class name to identify these configuration objects.

Returns:

Current String value assigned.

See Also:

setClassName(java.lang.String)

setSourceName

public void setSourceName(String val)

Set the source name of the configuration file.

Set's the "name" of the configuration file. Note, this is the simple name of the configuration file - it typically does not contain any path or extension information. By omitting path and extension information, the defaults will be applied. Refer to getFile() to see how this string is combined to form the actual file name.

NOTE: If you really need to force the path and extension information for the file, you can specify the full location of where you would like the file to be. For example, if you specify "/etc/com/ccg/io/default.MyConfig", then that is the file that will be used. However, in doing so, you must specify ALL information.

Parameters:

val - New String value to assign.

See Also:

getSourceName()

getSourceName

public String getSourceName()

Get the source name of the configuration file.

If a name hasn't been explicitly set, the default ("default") will be returned. It should be noted, that this is typically the "simple" name of the configuration file (it doesn't contain any path or extension information). For the full file name, use the getFile() method.

Returns:

Current String value assigned.

See Also:

setSourceName(java.lang.String)

getAvailableConfigs

public String[] getAvailableConfigs()

Get list of available configurations.

This method returns the "simple" names of ALL of the currently available configuration files that have been saved to disk (which can then be passed to setSourceName(java.lang.String)).

Returns:

Array of available configurations - never returns null, but may return a zero length list.

removeConfig

public void removeConfig()
                  throws IOException

Remove the configuration from existance.

This method attempts to delete the configuration (file) which the ConfigSource currently is pointing at.

Parameters:

cname - Name of the configuration to be removed - must not be null.

Throws:

IOException - If there is a problem removing the configuration (didn't exist, insufficient permissions, etc).

Since:

1.0

See Also:

getFile(), setSourceName(java.lang.String)

getFile

public File getFile()

Get's file representation of where the configuration is located at.

This method builds the full representation of where the configuration file should be located at. Currently, this can result in a rather LONG path. For example, if you had derived an object from this class called: "com.ccg.run.RunConfig", then the config files for this class would be created in the form:

 $HOME/.etc/com/ccg/run/NAME.RunConfig
 

The "$HOME" represents the user's home directory (as indicated by the JVM), and the "NAME" represents the name of the configuration to open (it will be "default" until the setSourceName(java.lang.String) method is used to change it.

It should be noted that if the object does not belong to a package, the name will be of the form:

 $HOME/.etc/jconf/NAME.CLASS
 

If you use the setSourceName(NAME) method, you have the option of using a full path/extension filename to force the configuration to be at a certain location (however, this is typically frowned upon - try to stick with simple names and use the default path/extensions generated).

Returns:

A File object that can be used to open the config file.

Since:

1.0

See Also:

createOutputStream(), openInputStream()

createOutputStream

public OutputStream createOutputStream()
                                throws ConfigException

Attempts to open a OutputStream for the purpose of saving.

When you are ready to save your configuration, you can use this method to open a OutputStream to write to. This method will create the necessary directories and then open the file as a stream.

Returns:

The OutputStream to write to (never returns null).

Throws:

ConfigException - If we are unable to open/create the output stream.

Since:

1.0

See Also:

getFile(), createObjectOutputStream(), createPrintWriter()

createPrintWriter

public PrintWriter createPrintWriter()
                              throws ConfigException

Attempts to open a PrintWriter for the purpose of saving.

If you are saving your configuration as a ASCII representation, you can use this method to open a PrintWriter to write to. This method will create the necessary directories and then open the file such that you can 'print' information to it.

Returns:

The PrintWriter to write to (never returns null).

Throws:

ConfigException - If we are unable to open/create the output.

Since:

1.0

See Also:

getFile(), createOutputStream()

openInputStream

public InputStream openInputStream()
                            throws ConfigException

Attempts to open a InputStream for the purpose of reading.

When you are ready to load your configuration, you can use this method to open a InputStream to read from. If the config file isn't found, a exception will be thrown. This is the counterpart to createOutputStream().

Returns:

The InputStream to read from (never returns null).

Throws:

ConfigException - If we are unable to open the input stream.

Since:

1.0

See Also:

getFile(), openObjectInputStream(), openLineNumberReader()

openLineNumberReader

public LineNumberReader openLineNumberReader()
                                      throws ConfigException

Attempts to open a LineNumberReader for the purpose of reading.

If you had previously saved your configuration as ASCII text using a PrintWriter, you can use this method to open the configuration file in a manner that you can read it back in. This is the counterpart to createPrintWriter().

Returns:

The LineNumberReader to read ASCII text from (never returns null).

Throws:

ConfigException - If we are unable to open the file.

Since:

1.0

See Also:

getFile(), openInputStream()

createObjectOutputStream

public ObjectOutputStream createObjectOutputStream()
                                            throws ConfigException

Attempts to open a ObjectOutputStream for the purpose of saving.

If you are saving your configuration as serialized objects, you can use this method to open a ObjectOutputStream to write to. This method will create the necessary directories and then open the file such that you can serialize data to it.

Returns:

The ObjectOutputStream to write to (never returns null).

Throws:

ConfigException - If we are unable to open/create the output.

Since:

1.0

See Also:

getFile(), createOutputStream()

openObjectInputStream

public ObjectInputStream openObjectInputStream()
                                        throws ConfigException

Attempts to open a ObjectInputStream for the purpose of reading.

If you had previously saved your configuration as serialized Java objects, you can use this method to open the configuration file in a manner that youcan read them back in. This is the counterpart to createObjectOutputStream().

Returns:

The ObjectInputStream to read objects from (never returns null).

Throws:

ConfigException - If we are unable to open the stream.

Since:

1.0

See Also:

getFile(), openInputStream()

saveObject

public void saveObject(Object object)
                throws ConfigException

Save single Object as entire configuration.

If your configuration can be represented as a single Serializable object, you can use this method to save it to disk. The ConfigAttributes object is highly recommended for this purpose. This method does the following:

• Opens the output file (creating any directories as needed).
• Writes your Object to the file.
• Closes the file.

To later retrieve the configuration, you would use the loadObject() method.

Parameters:

obj - The Serializable object to write out.

Throws:

ConfigException - If there is a problem creating/writing to the file

Since:

1.0

See Also:

loadObject()

loadObject

public Object loadObject()
                  throws ConfigException

Load a single Object as entire configuration.

If your configuration can be represented as a single Serializable object, you can use this method to load it back from disk. The ConfigAttributes object is highly recommended for this purpose. This method does the following:

• Opens the output file (creating any directories as needed).
• Reads your Object from the file.
• Closes the file.

Typically a configuration object that is loaded this way was previously stored using the saveObject(java.lang.Object) method.

Returns:

The Serializable object we read back in.

Throws:

ConfigException - If there is a problem opening/reading to the file (triggered by a IOException). Or, if we don't have knowledge of the class we are trying to de-serialize (class isn't found in the class path - triggered by a ClassNotFoundException).

Since:

1.0

See Also:

saveObject(java.lang.Object)

saveProperties

public void saveProperties(Properties props)
                    throws ConfigException,
                           IOException

Saves the set of properties specified in a manner that they can be loaded in the future.

This method attempts to save the set of Properties you pass to the current configuration file in a manner that it can be loaded in the future.

Parameters:

props - The properties to be saved - must not be null.

Throws:

ConfigException - If there is a problem with the configuration

IOException - If there is a problem opening, reading or closing the associated file.

Since:

1.0

loadProperties

public LookupProperties loadProperties()
                                throws ConfigException,
                                       IOException

Loads the set of properties which had been previously saved.

This method attempts to load the set of properties which had been saved at some time in the past.

Parameters:

props - The properties which were loaded (extended version of Properties) - does not return null.

Throws:

ConfigException - If there is a problem with the configuration

IOException - If there is a problem opening, reading or closing the associated file.

Since:

1.0