com.ccg.values
Class ValuesFactoryTree

java.lang.Object
  com.ccg.values.ValuesFactoryTree

public class ValuesFactoryTree
extends Object

A "factory" used to create and optionally edit objects which have an associated ValuesEditor and ValuesConfig.

This class provides many useful features to the end developer. It manages a collection of ValuesEditor and ValuesConfig implementations which you register and provides the following features:

• Creates a graphical component allowing the user to view/edit with the registered implementations.
• Allows the user to create new configurations for each registered type.
• Allows the user to remove existing configurations for each registered type.
• Allows the user edit and then save configurations for each registered type.
• Allows the user cancel edits and revert to the prior state.
• Allows the user to select from existing configurations and loads them into the editor.
• Allows the application to fetch a configuration corresponding to the last selected value for each of the registered types (or just the active selection).
• Allows the application to create and initialize a object associated with a particular configuration.

Though this class is not really intended to be run from the command line, it provides a simple main method which allows one to test their ValuesConfig and ValuesEditor implementations. It is invoked via the command line in the following manner:

 java com.ccg.values.ValuesVactoryTree -vf.0.text NAME -vf.0.editor CLASS \
    -vf.0.config CLASS
 

For example, lets assume one had created a editor implementation in com.glatmos.ld.swing.QueryDAEditor and a config implementation in com.glatmos.ld.swing.QueryDAConfig. You could use the following command line to bring up a window which would allow one to view, edit, create and delete configurations:

 java com.ccg.values.ValuesFactoryTree -vf.0.text DA \
   -vf.0.editor com.glatmos.ld.swing.QueryDAEditor \
   -vf.0.config com.glatmos.ld.swing.QueryDAConfig
 

One should notice the pattern of "-vf.0.*" in the above command line. You can load multiple editors/configs by specifying "-vf.1.*" values, "-vf.2.*" values, and so on (the addFromLookup rules are in affect). The following command line arguments are recognized:

-vf.N.text LABEL

The label to display in the parent node of the available configurations.

-vf.N.editor CLASS

The name of the class which implements the appropriate ValuesEditor.

-vf.N.config CLASS

The name of the class which implements the appropriate ValuesConfig.

The following is the implementation of the main method which constructs a ValuesFactoryTree, dynamically loads it via the addFromLookup, stick the GUI component into a JFrame and displays it:

  public static void main(String[] args) {
    CommandLine cmdLine = new CommandLine(args);
    ValuesFactoryTree vft = new ValuesFactoryTree();
    int cnt = vft.addFromLookup(cmdLine,"vf");
    if (cnt == 0) {
      System.err.println("Usage: java com.ccg.values.ValuesFactoryTree "+
                         "-vf.0.text Name \\");
      System.err.println("       -vf.0.editor CLASS -vf.0.config CLASS");
      System.exit(1);
    }
    JFrame frame = new JFrame("Config Editor");
    frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
    frame.setContentPane(vft.getComponent());
    frame.pack();
    frame.show();
  }
 

Since:

1.0

Version:

$Revision: 1.8 $

Author:

$Author: pkb $

See Also:

ValuesHolder, ValuesEditor, ValuesConfig

Nested Class Summary

(package private) class	ValuesFactoryTree.Choice
(package private) class	ValuesFactoryTree.QeFolderNode
(package private) class	ValuesFactoryTree.QeNode

Field Summary

(package private) Hashtable	_Choices
(package private) JComponent	_Component
(package private) JButton	_Delete
(package private) JPanel	_Editors
(package private) Vector	_NameOrder
(package private) JButton	_New
(package private) JButton	_Revert
(package private) JButton	_Save
(package private) ValuesFactoryTree.Choice	_Selected
(package private) JTree	_Tree

Constructor Summary

ValuesFactoryTree()
Construct the object with nothing registered.

Method Summary

void	add(String name, ValuesEditor ve, ValuesConfig vc, Object tobj) Registers (adds/replaces) a single editor/config within the factory.
int	addFromLookup(Lookup baseLookup, String tag, Class oclass) Register a set of zero or more ValuesConfig/ValuesEditor pairings with the factory.
Object	createObjectInstance(String gname, String cname) Create a new instance of a object corresponding to a specific group name.
JComponent	getComponent() Get the Swing component which the user interacts with to choose and edit the values.
Iterator	getGroupKeys() Get the names of ALL of the registered config/editors.
String	getSelectedConfig(String gname) Get the name of the registered config/editor which is currently selected.
String	getSelectedGroup() Get the name of the registered config/editor which is currently selected.
ValuesConfig	getValuesConfig(String name) Get the ValuesConfig which was registered under a specific name.
ValuesEditor	getValuesEditor(String name) Get the ValuesEditor which was registered under a specific name.
boolean	isDirty() Determine if the user has made modifications to the current entry, but not saved them.
static void	main(String[] args) Starts up GUI test application.
boolean	performSave() Foces the saving of any user modifications (as if user pressed the "Save" button).
ValuesConfig	setSelected(String name, String cname) Specify which ValuesEditor and (optionally) configuration is to be the current "selected" one for the factory.
int	showConfirmDialog(Component p, Resources r, String tag) Show the editor within a dialog box with a OK/Cancel button.

Methods inherited from class java.lang.Object

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

Field Detail

_NameOrder

Vector _NameOrder

_Choices

Hashtable _Choices

_Selected

ValuesFactoryTree.Choice _Selected

_Component

JComponent _Component

_Editors

JPanel _Editors

_Tree

JTree _Tree

_New

JButton _New

_Delete

JButton _Delete

_Save

JButton _Save

_Revert

JButton _Revert

Constructor Detail

ValuesFactoryTree

public ValuesFactoryTree()

Construct the object with nothing registered.

After constructing the factory in the method, one will want to use one or more of the "add" methods to register the different real time connections they would like their application to support.

Since:

1.0

Method Detail

getGroupKeys

public Iterator getGroupKeys()

Get the names of ALL of the registered config/editors.

Returns:

A non-null iterator of all of the groups which this editor manages.

Since:

1.0

See Also:

getValuesConfig(java.lang.String), getValuesEditor(java.lang.String)

getValuesConfig

public ValuesConfig getValuesConfig(String name)

Get the ValuesConfig which was registered under a specific name.

This can be particularily useful if one wants to save the name of the configuration which is in affect for the editor.

Parameters:

name - The name which the values configuration was previosly registered under.

Returns:

The values configuration associated with the specified name, or null if one has not been registered.

Since:

1.0

See Also:

getGroupKeys()

getValuesEditor

public ValuesEditor getValuesEditor(String name)

Get the ValuesEditor which was registered under a specific name.

Parameters:

name - The name which the values editor was previosly registered under.

Returns:

The values editor associated with the specified name, or null if one has not been registered.

Since:

1.0

See Also:

getGroupKeys()

add

public void add(String name,
                ValuesEditor ve,
                ValuesConfig vc,
                Object tobj)
         throws IllegalStateException,
                IllegalArgumentException

Registers (adds/replaces) a single editor/config within the factory.

Parameters:

name - Name for the editor type (must not be null).

ve - The ValuesEditor to associate with the name (used for GUI component to edit values) - must not be null.

vc - The ValuesConfig to load/save values to disk, must work with the same class of objects as the values editor and must not be null.

tobj - The Object to be used when values need to be transferred from the configuration to the editor or vice versa. You can also pass null if its OK for us to just use the 've' to create a instance of the object (which should work for most people).

Throws:

IllegalStateException - If the editor has already been created (all registration must be done PRIOR to creating a instance of the editor).

IllegalArgumentException - If the ValuesConfig/ValuesEditor don't work for the same class of objects, or we are unable to use/create the transfer object.

Since:

1.0

addFromLookup

public int addFromLookup(Lookup baseLookup,
                         String tag,
                         Class oclass)

Register a set of zero or more ValuesConfig/ValuesEditor pairings with the factory.

This method is particularily handy when you want to use a configuration file (or some other run time information coerced into a Lookup table) to configure what implementations the factory will provide.

For an example, the following property file could be constructed to install 2 possible connection types (each of which could have MANY configurations):

 vf.0.text=Time Span
 vf.0.editor=com.ccg.swing.TimeSpanEditor
 vf.0.config=com.ccg.io.TimeSpanConfig
 vf.1.text=Login
 vf.1.editor=com.ccg.swing.LoginEditor
 vf.1.config=com.ccg.io.LoginConfig
 

This method checks for values for "TAG.N.text", "TAG.N.editor" and "TAG.N.config" (where N starts at 0 and increments). Each time a value is found for all of these keys, a attempt is made to create a instance of the "TAG.N.editor" and "TAG.N.config" objects. If successful, the add method is then used to register the name/instance with the factory.

If a failure occurs, the failed item is skipped and any remaining items are loaded. This allows one to dynamically change the available configurations simply by removing necessary class files and/or by adjusting the properties used in the invocation of this method.

Parameters:

l - Lookup table to look for configuration info described above - must not be null.

tag - The TAG which is used as a prefix for the values loaded (shown as vf in the above example, but you can use whatever you want). Must not be null.

oclass - This allows one to do a sanity check on the editor/config combinations that are added. In order for either to be accepted, the object class which they are designed to work with must either match this class, or be an instance of this class. If you pass null, we'll treat it as Object.class which causes us to accept anything.

Returns:

Number of implementations that were actually registered.

Throws:

IllegalStateException - If the editor has already been created (all registration must be done PRIOR to creating a instance of the editor).

Since:

1.0

setSelected

public ValuesConfig setSelected(String name,
                                String cname)

Specify which ValuesEditor and (optionally) configuration is to be the current "selected" one for the factory.

Parameters:

name - The name which the editor/config was registered under, or null to unselect.

cname - The configuration name (null to unselect).

Returns:

The ValuesConfig which is active for the specified selection (or null nothing selected - or invalid choice).

Since:

1.0

getSelectedGroup

public String getSelectedGroup()

Get the name of the registered config/editor which is currently selected.

Returns:

The name of the group which is currently selected or null if no group is currently selected.

Since:

1.0

getSelectedConfig

public String getSelectedConfig(String gname)

Get the name of the registered config/editor which is currently selected.

Parameters:

gname - The name of the group (what the editor/config pair was registered under). You may pass null (in which case you get null back).

Returns:

The name of the configuration which is currently selected for the group sepcified or null if no group is currently selected.

Since:

1.0

See Also:

getSelectedGroup()

createObjectInstance

public Object createObjectInstance(String gname,
                                   String cname)
                            throws IOException,
                                   ConfigException,
                                   UnsupportedOperationException,
                                   IllegalArgumentException

Create a new instance of a object corresponding to a specific group name.

After you register the various config/editor types which the factory will manage, you can use this method to retrieve a new instance of a Object object that is limited to one of the registered groups.

This method is typically used when a application starts up and wants to create a initial instance of a object without constructing Swing components.

Parameters:

gname - The ASCII name which the config/editor was originally registered with.

cname - Pass the name of a configuration (typically from getSelectedConfig) which you would like to initialize the object with after creating it. OR, pass null to just create new instance.

Returns:

A newly created object which is appropriate for the registered name spacified (possibly initialized with either the last configuration selected for this group, or the default configuration).

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.

UnsupportedOperationException - If the values editor is designed for either a interface or abstract class or can not come up with some reasonable defaults. This should be unexpected and indicates that you've registered a inappropriate ValuesEditor implementation with the factory.

IllegalArgumentException

Since:

1.0

main

public static void main(String[] args)

Starts up GUI test application.

Parameters:

args - Command line arguments. At a minimum "-class CLASS" must be specified.

Since:

1.0

getComponent

public JComponent getComponent()

Get the Swing component which the user interacts with to choose and edit the values.

NOTE: Once the Swing component is realized (after the first time you invoke this method), it is illegal to attempt to register any new real time connection types (the "add" methods will throw an exception on you).

Returns:

The GUI component for the user to interact with.

Since:

1.0

isDirty

public boolean isDirty()

Determine if the user has made modifications to the current entry, but not saved them.

Returns:

true if user has made changes but not committed them, false if not.

Since:

1.0

See Also:

performSave()

performSave

public boolean performSave()

Foces the saving of any user modifications (as if user pressed the "Save" button).

It is possible that a User could make modifications to the various fields associated with the component and then attempt to close the GUI component via some other mechanism (this can easily happen when added to a larger window with its own "OK" button). This method allows one to force the saving of any changes made by the user.

NOTE: This method does nothing if the GUI component has not been realized.

Returns:

true if save was successful or not needed, false if save required, but failed.

Since:

1.0

showConfirmDialog

public int showConfirmDialog(Component p,
                             Resources r,
                             String tag)

Show the editor within a dialog box with a OK/Cancel button.

This method uses the showConfirmDialog method found in the Resources class to present a dialog box to the user containing the "tree editor" plus an additional OK/Cancel button.

This allows the user to select a choice from the tree and to optionally modify any of the contained values.

If the user presses the OK button on the dialog box, and their are unsaved edits, this method will attempt to save the editted values. If the save fails, it will report a error and reshow the dialog box to allow the user to correct for the situation.

This is a "modal" dialog box (this method does not return until the user finishes interacting with the dialog).

Parameters:

parent - Parent component for the dialog (see JOptionPane).

r - Resource object to retrieve information for building the dialog (must not be null).

tag - The tag in the resource file used to lookup dialog properties with.

Returns:

Integer return code as defined by the JOptionPane class (indicating what option the user selected).

Since:

1.0

See Also:

Resources.showConfirmDialog(java.awt.Component, java.lang.Object, java.lang.String, java.lang.Object[], int)