com.ccg.values
Class ValuesConfigBean

java.lang.Object
  com.ccg.values.ValuesConfigBean

All Implemented Interfaces:

ValuesConfig, ValuesHolder

public class ValuesConfigBean
extends Object
implements ValuesConfig

A 'generic' ValuesConfig implementation for beans (uses XML).

The ValuesConfigBean is used to to store and load the values from bean style Java classes as XML files. This class takes care of most of the headaches for you by using the magic provided by XMLEncoder and XMLDecoder. You just need to worry about the following:

• Making sure your bean class has a public default constructor.
• Make sure your bean class has both the get/set methods or is/set methods available for the data it encapsulates.
• Use simple and unique names when saving/loading (as we will form file names from what you provide).

The following demonstrates how one might use this object to save and load a Email bean:

import com.ccg.values.ValuesConfigBean;

public class Email {

  public static void main(String[] args) {
                        // Show usage if invalid args
    if (args.length != 1 && args.length != 3) {
      System.out.println("Usage: java Email ALIAS [NAME EMAIL]");
      System.exit(1);
    }

                        // Load configuration based on ALIAS
    ValuesConfigBean vcb = new ValuesConfigBean(Email.class);
    try {
      vcb.load(args[0]);
    } catch (Exception ignore) {
      if (args.length == 1) {
        System.err.println("No configuration found for:"+args[0]);
        System.exit(2);
      }
    }

                        // Transfer values loaded into a new Email object
    Email email = new Email();
    vcb.toObject(email);

                        // If new values on command line 
    if (args.length == 3) {
                        // store them in the bean
      email.setName(args[1]);
      email.setEmail(args[2]);

      try {             // lets archive it for future availability
        vcb.fromObject(email);
        vcb.save(args[0]);
      } catch (Exception saveErr) {
        System.err.println("failed to save "+email+" under:"+args[0]);
        System.exit(2);
      }
    }

                        // Display current state of bean
    System.out.println("Email associated with:"+args[0]);
    System.out.println("  "+email);
  }

  public Email() { _Name=_Email="unknown"; }

  public String getName() { return _Name; }
  public void setName(String name) { if (name != null) _Name = name; }

  public String getEmail() { return _Email; }
  public void setEmail(String email) { if (email != null) _Email = email; }

  public String toString() { return _Name+" <"+_Email+'>'; }

  private String _Name;
  private String _Email;
}
 

The beauty of thie arrangement is that we really didn't have to worry too much on the mechanics of saving/loading the values of our bean. We just made sure it behaved like a good bean and then let the ValuesConfigBean do the rest of the work for us. The following shows some results from compiling and running the above example:

[pkb@salsa tmp]$ jikes Email.java
[pkb@salsa tmp]$ java Email
Usage: java Email ALIAS [NAME EMAIL]
[pkb@salsa tmp]$ java Email paul
No configuration found for:paul
[pkb@salsa tmp]$ java Email paul "Paul Blankenbaker" paul@mekwin.com
Email associated with:paul
  Paul Blankenbaker <paul@mekwin.com>
[pkb@salsa tmp]$ java Email paul
Email associated with:paul
  Paul Blankenbaker <paul@mekwin.com>
[pkb@salsa tmp]$ java Email megan "Megan Brown" megan@mekwin.com
Email associated with:megan
  Megan Brown <megan@mekwin.com>
[pkb@salsa tmp]$ java Email paul
Email associated with:paul
  Paul Blankenbaker <paul@mekwin.com>
[pkb@salsa tmp]$ java Email megan
Email associated with:megan
  Megan Brown <megan@mekwin.com>
[pkb@salsa tmp]$ ls $HOME/.etc/jconf/*.Email
/home/pkb/.etc/jconf/megan.Email  /home/pkb/.etc/jconf/paul.Email
[pkb@salsa tmp]$ cat $HOME/.etc/jconf/paul.Email
<?xml version="1.0" encoding="UTF-8"?>
<java version="1.4.2_02" class="java.beans.XMLDecoder">
 <object class="Email">
  <void property="email">
   <string>paul@mekwin.com</string>
  </void>
  <void property="name">
   <string>Paul Blankenbaker</string>
  </void>
 </object>
</java>
[pkb@salsa tmp]$
 

Since:

1.0

Version:

$Revision$

Author:

$Author$

See Also:

ValuesEditorBean

Field Summary

(package private) Method[]	_GetMethods
(package private) Method[]	_SetMethods

Fields inherited from interface com.ccg.values.ValuesHolder

HAS_FROM, HAS_TO, HAS_TO_FROM

Constructor Summary

ValuesConfigBean(Class c)
Construct a ValuesConfigBean object for a certain class.

Method Summary

Object	checkArgument(Object o) Verify that a object is of the type recognized by this class.
void	fromObject(Object o) Transfer values from a object into this "value holder".
String[]	getAvailable() Get list of available configurations.
int	getCapabilities() Determine what the ValuesHolder implementation supports.
String	getDefaultName() Get the default name for the ValuesConfig implementation.
Class	getObjectClass() Get the Class which the "values holder" is designed to work with.
void	load(String name) Attempts to load a configuration from the specified name.
void	remove(String name) Remove a configuration from existance.
void	save(String name) Saves the current configuration in a manner that it can be loaded in the future.
void	toObject(Object o) Transfer values from this "value holder" into a object.
String	toString() Get a simple string representation of the ValuesConfig implementation.

Methods inherited from class java.lang.Object

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

Field Detail

_SetMethods

Method[] _SetMethods

_GetMethods

Method[] _GetMethods

Constructor Detail

ValuesConfigBean

public ValuesConfigBean(Class c)

Construct a ValuesConfigBean object for a certain class.

Parameters:

c - Class to of bean to handle configuration of - MUST not be null, and must support the Class.newInstance() method.

Throws:

IllegalArgumentException - If the Class you pass is invalid (we were unable to create a Object instance).

Since:

1.0

Method Detail

getCapabilities

public int getCapabilities()

Determine what the ValuesHolder implementation supports.

This method returns HAS_TO_FROM indicating that the ValuesHolder interface is fully supported. This means that values can be transferred in both directions - from the object to the properties configuration and from the properties configuration to the object. Any derived class which does not support either of these operations, will need to override this method and indicate what they do support.

Specified by:

getCapabilities in interface ValuesHolder

Returns:

ValuesHolder.HAS_TO_FROM.

Since:

1.0

See Also:

ValuesHolder.getCapabilities()

getDefaultName

public final String getDefaultName()

Get the default name for the ValuesConfig implementation.

Sometimes, one doesn't want to worry about choosing between available configurations for a object - they simply want to work with the 'default' configuration - or a application may only need one configuration. In these cases, one can simply use this method to retrieve the name for the 'default' configuration and then use this name with the save and load methods.

Please note that the name returned does NOT guarantee existance of the configuration (in other words a load of the default name might fail) - someone must save a configuration under the default name before it can be loaded.

Specified by:

getDefaultName in interface ValuesConfig

Returns:

A 'default' name suitable as a parameter to the save and load methods.

Since:

1.0

getAvailable

public final String[] getAvailable()

Get list of available configurations.

This method returns the "simple" names of ALL of the currently available configuration files that are available for loading.

Specified by:

getAvailable in interface ValuesConfig

Returns:

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

save

public final void save(String name)
                throws IOException,
                       ConfigException

Saves the current configuration in a manner that it can be loaded in the future.

This method attempts to permanently save the state of the "values holder" in a manner that it can be loaded in the future.

Specified by:

save in interface ValuesConfig

Parameters:

name - Name or key which configuration is to be saved under (typically in a simple form like: "liveoak" - don't assume a file system). Must not be null.

Throws:

ConfigException - If there is a problem with the configuration

IOException - If there is a problem trying to write the configuration to its final location.

Since:

1.0

See Also:

load(java.lang.String)

load

public final void load(String name)
                throws IOException,
                       ConfigException

Attempts to load a configuration from the specified name.

This method attempts to load the values back from a configuration which had previously been saved.

Specified by:

load in interface ValuesConfig

Parameters:

name - Name or key which configuration is to be loaded (typically in a simple form like: "liveoak" - don't assume a file system). Must not be null.

Throws:

ConfigException - If there is a problem with the configuration

IOException - If there is a problem trying to read the configuration from the system/network.

Since:

1.0

remove

public final void remove(String name)
                  throws IllegalArgumentException,
                         IOException

Remove a configuration from existance.

This method attempts to delete the configuration specified.

Specified by:

remove in interface ValuesConfig

Parameters:

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

Throws:

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

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

Since:

1.0

checkArgument

public final Object checkArgument(Object o)
                           throws NullPointerException,
                                  IllegalArgumentException

Verify that a object is of the type recognized by this class.

This method is typically used by the toObject and fromObject methods. It verifies that the object is of the proper type (and throws an exception if not).

Returns:

The object passed (never returns null)

Throws:

NullPointerException - If you pass null.

IllegalArgumentException - If the object you pass is not a instance of the object class supported.

Since:

1.0

toString

public String toString()

Get a simple string representation of the ValuesConfig implementation.

Overrides:

toString in class Object

Returns:

A simple string identifying this class and the bean class it has been associated with.

Since:

1.0

getObjectClass

public Class getObjectClass()

Get the Class which the "values holder" is designed to work with.

This method returns the Class which the "values holder" is designed to work with. All objects which are passed to the toObject or fromObject methods MUST be instances of this class.

Specified by:

getObjectClass in interface ValuesHolder

Returns:

The class this "values holder" is designed to work with - never returns null.

Since:

1.0

toObject

public void toObject(Object o)
              throws IllegalStateException,
                     IllegalArgumentException,
                     UnsupportedOperationException,
                     NullPointerException

Transfer values from this "value holder" into a object.

This method restores the state information by invoking all of the "set" methods which have a corresponding "get" or "is" method in your bean class. Its possible that we will only get a partial transfer (an exception will be thrown in this condition) if one of the underlying "is", "get" or "set" methods we invoke during the transfer fails on us.

Specified by:

toObject in interface ValuesHolder

Throws:

NullPointerException - If you pass null.

IllegalArgumentException - If the object passed is not the proper type.

IllegalStateException - If the "values holder" isn't in the proper state to do the transfer.

UnsupportedOperationException - If the "value holder" doesn't implement the setting of values in the associated objects.

Since:

1.0

See Also:

fromObject(java.lang.Object)

fromObject

public void fromObject(Object o)
                throws IllegalStateException,
                       IllegalArgumentException,
                       UnsupportedOperationException,
                       NullPointerException

Transfer values from a object into this "value holder".

This method saves the state information from all of the "get" and "is" methods of the bean class that have a corresponding "set" method. Its possible that we will only get a partial transfer (an exception will be thrown in this condition) if one of the underlying "is", "get" or "set" methods we invoke during the transfer fails on us.

Specified by:

fromObject in interface ValuesHolder

Throws:

NullPointerException - If you pass null.

IllegalArgumentException - If the object passed is not the proper type.

IllegalStateException - If the object isn't in the proper state to do the transfer into this "values holder".

UnsupportedOperationException - If the "value holder" doesn't implement the getting of values from associated objects.

Since:

1.0

See Also:

toObject(java.lang.Object)