com.ccg.values
Class ValuesPropertiesAdapter

java.lang.Object
  com.ccg.values.ValuesPropertiesAdapter

All Implemented Interfaces:

ValuesConfig, ValuesHolder

public abstract class ValuesPropertiesAdapter
extends Object
implements ValuesConfig

A base ValuesConfig implementation which stores the values held in standard Java property files.

This base class is used when creating a ValuesConfig implementation which will use Java style properties files for saving/loading values. It does most of the work.

A developer should which uses this as a base should only need to deal with the task of implementing the ValuesHolder methods getObjectClass, toObject and fromObject. In addition, the implementation of the toObject and fromObject only need to worry about transferring values between the associated object and the internal properties (which you get a reference to via getConfig. Here is a simple example:

import com.ccg.util.TagLookup;
import com.ccg.values.ValuesPropertiesAdapter;

import java.util.Properties;

class Person {

  public String getFirstName() { return _FirstName; }
  public void setFirstName(String fn) { _FirstName = nullCheck(fn); }

  public String getLastName() { return _LastName; }
  public void setLastName(String ln) { _LastName = nullCheck(ln); }

  public String toString() {
    return ""+_FirstName+" "+_LastName;
  }

  public Person() {
    _FirstName = _LastName = UNKNOWN;
  }

  public Person(String fn, String ln) throws NullPointerException {
    setFirstName(fn);
    setLastName(ln);
  }


  static String nullCheck(String s) {
    if (s == null) throw new NullPointerException();
    return s;
  }

  public static void main(String[] args) {
    int ac = args.length;
    if (ac == 1) try {
                                // try to load config
      PersonConfig pc = new PersonConfig();
      pc.load(args[0]);
      Person p = new Person();
      pc.toObject(p);
      System.out.println("Loaded:"+p+"  from:"+args[0]);
    } catch (Exception eload) {
      System.err.println("problem trying to load config:"+args[0]);
      eload.printStackTrace();
    } else if (ac == 3) try {
      Person p = new Person(args[1],args[2]);
      PersonConfig pc = new PersonConfig();
      pc.fromObject(p);
      pc.save(args[0]);
    } catch (Exception esave) {
      System.err.println("problem trying to save config:"+args[0]);
      esave.printStackTrace();
    } else {
      System.out.println("Usage:  java Person CONFIG [FIRST LAST]");
      System.out.println();
      System.out.println("Where:  java Person pkb Paul Blankenbaker");
      System.out.println("  Creates Person object and saves under "+
                         "config \"pkb\"");
      System.out.println();
      System.out.println("Where:  java Person pkb");
      System.out.println("  Attempts to load Person object from "+
                         "config \"pkb\"");
    } 
  }

  static final String UNKNOWN = "unknown";

  private String _FirstName;
  private String _LastName;
}


class PersonConfig extends ValuesPropertiesAdapter {
  public Class getObjectClass() {
    return Person.class;
  }

  public void toObject(Object o) throws IllegalStateException, 
                                        IllegalArgumentException, 
                                        UnsupportedOperationException,
                                        NullPointerException {
    Person p = (Person) checkArgument(o);
    TagLookup tl = new TagLookup(getConfig());
    p.setFirstName(tl.getString(FN_KEY,Person.UNKNOWN));
    p.setLastName(tl.getString(LN_KEY,Person.UNKNOWN));
  }

  public void fromObject(Object o) throws IllegalStateException, 
                                          IllegalArgumentException, 
                                          UnsupportedOperationException,
                                          NullPointerException {
    Person p = (Person) checkArgument(o);
    Properties cfg = getConfig();
    cfg.put(FN_KEY,p.getFirstName());
    cfg.put(LN_KEY,p.getLastName());
  }

  static final String FN_KEY = "fn";
  static final String LN_KEY = "ln";

}

 

Since:

1.0

Version:

$Revision: 1.3 $

Author:

$Author: pkb $

Field Summary

Fields inherited from interface com.ccg.values.ValuesHolder

HAS_FROM, HAS_TO, HAS_TO_FROM

Constructor Summary

ValuesPropertiesAdapter()

Method Summary

Object	checkArgument(Object o) Verify that a object is of the type recognized by this class.
String[]	getAvailable() Get list of available configurations.
int	getCapabilities() Determine what the ValuesHolder implementation supports.
protected LookupProperties	getConfig() Get the properties used to configure the object.
String	getDefaultName() Get the default name for the ValuesConfig implementation.
Enumeration	getKeys() Retrieve the set of available keys in the table.
String	getString(String key) Retrieve the string value associated with a key in the "values holders" properties.
String	getString(String key, String def) Retrieve the string value associated with a key in the "values holders" properties.
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.
String	toString() Get a simple string representation of the configuration.
static void	transferProperties(Properties dst, Properties src, String[] keys) Transfers property key/values from a source to a destination.
protected boolean	validate(LookupProperties cfg) Validate and/or correct a set of configuration properties.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.ccg.values.ValuesHolder

fromObject, getObjectClass, toObject

Constructor Detail

ValuesPropertiesAdapter

public ValuesPropertiesAdapter()

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:

A 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

getConfig

protected final LookupProperties getConfig()

Get the properties used to configure the object.

Returns:

The properties table used to hold configuration - never returns null - but may return a empty set of properties.

getKeys

public final Enumeration getKeys()

Retrieve the set of available keys in the table.

Returns:

A non-null iterator of the available keys.

Since:

1.0

See Also:

getString(java.lang.String)

getString

public final String getString(String key)

Retrieve the string value associated with a key in the "values holders" properties.

Parameters:

key - Name of the key to lookup - must not be null.

Returns:

A string value associated with a particular key (may return null).

Since:

1.0

See Also:

getKeys()

getString

public final String getString(String key,
                              String def)

Retrieve the string value associated with a key in the "values holders" properties.

Parameters:

key - Name of the key to lookup - must not be null.

def - Default value to return if key value is not set.

Returns:

A string value associated with a particular key (returns your default value if not found).

Since:

1.0

See Also:

getString(String)

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. It should be noted that the validate method will be invoked PRIOR to doing the save.

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. It should be noted that the validate method will be used to check the configuration loaded PRIOR to accepting it.

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

See Also:

validate(com.ccg.util.LookupProperties)

validate

protected boolean validate(LookupProperties cfg)
                    throws ConfigException

Validate and/or correct a set of configuration properties.

This method is used by the save/load to make sure that everything is OK prior to proceeding. This method returns true if everything was considered OK, it returns false if there were some problems, but the implementation was able to correct them (the properties passed were adjusted to valid values in this case). If the properties passed were unacceptable (not OK and we couldn't fix them) a exception is thrown.

This is merely a place holder (as this default implementation always returns true). Derived classes are permitted/encouraged to implement this method if there are sanity checks which should be done on any set of properites passed.

Parameters:

cfg - A configuration which is to be checked (and possibly fixed).

Returns:

true if the configuration passed was acceptable without change (nothing modified), false if the configuration passed was modified (in order to make it acceptable).

Throws:

ConfigException - If the set of properties passed is unacceptable and we were unable to fix them.

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

transferProperties

public static void transferProperties(Properties dst,
                                      Properties src,
                                      String[] keys)

Transfers property key/values from a source to a destination.

This method scans your src property table looking for values associated with the list of keys which you pass. If it finds a value, it inserts it into the dst specified. If it does not find a value, it removes any association in the dst for the key in question.

Parameters:

dst - Property table to be updated key/value pairs may be inserted, replaced or removed (must not be null).

src - Property table to copy from (must not be null).

keys - Array of keys which are to be transfered (must not be null).

Since:

1.0

toString

public String toString()

Get a simple string representation of the configuration.

Overrides:

toString in class Object

Returns:

A string representation (shows current key/value pairs).

Since:

1.0