com.taursys.model
Class DefaultSelectModel

java.lang.Object
  com.taursys.model.DefaultTextModel
      com.taursys.model.DefaultSelectModel

All Implemented Interfaces:

javax.swing.event.ChangeListener, java.util.EventListener, SelectModel, TextModel

public class DefaultSelectModel

extends DefaultTextModel

implements SelectModel

Implementation of the SelectModel which holds a list of options and the selected item. This model can be used in a variety of ways. It can be used in an un-bound mode, where the current selection is maintained internally. It can also be used in a bound mode where the current selection is propagated to a value holder. When used in the bound mode, either a single property, or multiple properties can be set in the value holder.

The following sections describe the required settings to make for each of the modes.

Un-bound Mode (uses internal VariantValueHolder)

When used in this mode this component uses an internal VariantValueHolder to hold the current selection. By default a VariantValueHolder is created with a data type of String. To set a different data type use the constructor which takes a data type as a parameter. (example new DefaultSelectModel(DataTypes.TYPE_INT)).

To use this component in the un-bound mode, you must set the following properties:

• list - should be set to a type of CollectionHolder which holds the list of options (see "Setting the List").
• displayPropertyName - the name of the property to display (property of objects in list). Example: given a list of "Location" objects with a property called "locationName", use setDisplayPropertyName("locationName") to display the zipCode. IMPORTANT - The displayed property choosen must result in a unique list of values, otherwise the intended value may not be selected/displayed.
• listPropertyNames - set a single source property name in the list objects. Example: Given a list containing "Location" objects which has properties "zipCode", "cityName", "stateAbbr", and "country", to make the zipcode the internal value use setListPropertyNames(new String[] {"zipCode"}).

  If the list is an ObjectArrayValueHolder, then the property name should always be a single "value" (which is the default).

• propertyName - must be "value" (which is the default).
• nullDisplay - String to display in list for null selection. Example: "--- Nothing Selected ---"

Bound Mode

To use this component in the bound mode, use the same properties as described in the Un-bound Mode, plus the following additional properties:

• valueHolder - should be set to the target ValueHolder which contains the current selection and will be updated if the selection is changed.
• propertyName - set this to the first (or only) ValueHolder object property name which will be bound to the selection. Example: given a ValueHolder with an "Address" object which has a "zipCode" property, use setPropertyName("zipCode") to store the current selection in the "Address.zipCode" property.
• propertyNames - use this when you want to set more than 1 property in the ValueHolder object. Example: assume you want to set not only the "zipCode" property, but also the "city", "state" and "country" properties, use setPropertyNames(new String[] {"zipCode","city","state","country"})
• listPropertyNames - set the to the source property name(s) in the list objects. IMPORTANT - The name(s) of the listPropertyNames properties MUST be in the same ORDER as the propertyName(s). The names in the listPropertNames may be different than the names in the propertyNames since they are associated with in objects in the list, not the valueHolder. Example: Given a list containing "Location" objects which has properties "zipCode", "cityName", "stateAbbr", and "country", for a single property use setListPropertyNames(new String[] {"zipCode"}). For multiple properties use setListPropertyNames(new String[] {"zipCode", "cityName", "stateAbbr", "country"})

  If the list is an ObjectArrayValueHolder, then the property name should always be a single "value" (which is the default).

Setting the List

The list must be a type of CollectionValueHolder (example: VOCollectionValueHolder or VOListValueHolder). The holder can contain any type of object (but they must all be instances of the same class).

If the list is an ObjectArrayValueHolder, then the toString() method is used as the display value (regardless of the displayPropertyName). If used in the bound mode, the whole object itself is stored in the target ValueHolder's object (regardless of the property names listed in the setListPropertyNames method). It is important to make sure that the valueHolder property is the same type as the objects in the ObjectArrayValueHolder or a ModelException will occur.

You can also preset the list in the constructor by passing it an array of Objects to be used for the list. The resulting list will be an ObjectArrayValueHolder.

Other Important Information

When a selection is made, the values are copied from the properties in the list to the properties in the valueHolder object. The property names in propertyNames[] and listPropertyNames[] must appear in a corresponding order.

A "null" item will always be added to the displayOptionList. When the "null" item is selected, a null will be assigned to the propertyNames[] in the valueHolder object. The actual "null" item to to display is defined by the nullDisplay (default is "--none--").

The format and formatPattern govern the display property in this component. The getText method returns the formatted display property, while the setText method changes the current selection to one whose display matches the given value. If you attempt to setText for an item that is not in the list, a NotInListException will be thrown.

Constructor Summary

DefaultSelectModel()
Constructs a new DefaultSelectModel The default valueHolder for this model is a String VariantValueHolder.

DefaultSelectModel(int javaDataType)
Constructs new DefaultSelectModel and sets valueHolder to a VariantValueHolder for given data type.

Method Summary

protected void	copyValues() Copies the corresponding values from the current listObject to the valueHolder object.
protected CollectionValueHolder	createDefaultList() Constructs a default list for this model.
protected ValueHolder	createDefaultValueHolder() Creates an ObjectValueHolder as the default ValueHolder for model.
protected java.lang.String	getCurrentPropertyValues()
java.util.Collection	getDisplayOptionList() Returns a Collection of the SelectModelOptions.
java.lang.String	getDisplayPropertyName() Returns the property name of the list object to display in the list.
CollectionValueHolder	getList() Returns collectionValueHolder which holds the collection of possible selections.
java.lang.String[]	getListPropertyNames() Returns array of property names in list object to copy to valueHolder object.
java.lang.String	getNullDisplay() Returns value to display in list for a null value.
java.lang.String	getPropertyName() Gets the property name in valueHolder that will hold the value from the list.
java.lang.String[]	getPropertyNames() Gets array of property names in valueHolder object that correspond to properties of list object.
java.lang.Object	getSelectedItem() Returns the currently selected item from the list.
java.lang.String	getText() Returns display value of current selection.
protected boolean	isCurrentMatch() Compares the corresponding property values of the current list with valueHolder object.
boolean	isNullAllowed() Returns indicator that a null value is a valid selection.
protected boolean	isValueNull() Returns true if all of the properties (propertyNames[]) are null.
void	setDisplayPropertyName(java.lang.String newDisplayPropertyName) Sets the property name of the list object to display in the list.
void	setList(CollectionValueHolder newList) Sets collectionValueHolder which holds the collection of possible selections.
void	setListPropertyNames(java.lang.String[] newListPropertyNames) Sets array of property names in list object to copy to valueHolder object.
void	setNullAllowed(boolean nullAllowed) Sets indicator that a null value is a valid selection.
void	setNullDisplay(java.lang.String newNullDisplay) Sets value to display in list for a null value.
protected void	setNullValues() Sets the propertyNames[] in the valueHolder object to null.
void	setPropertyName(java.lang.String newPropertyName) Sets the property name in valueHolder that will hold the value from the list.
void	setPropertyNames(java.lang.String[] newPropertyNames) Sets array of property names in valueHolder object that correspond to properties of list object.
void	setSelectedItem(java.lang.Object value) Sets the current selection by searching through the list for the given object.
void	setText(java.lang.String value) Sets the current selection by matching the given value to the list's display values.
java.lang.String	toString() Returns a string representation of this object.

Methods inherited from class com.taursys.model.DefaultTextModel

addChangeListener, fireStateChanged, getFormat, getFormatPattern, getValueHolder, removeChangeListener, setFormat, setFormatPattern, setupFormat, setValueHolder, stateChanged

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.taursys.model.TextModel

addChangeListener, getFormat, getFormatPattern, getValueHolder, removeChangeListener, setFormat, setFormatPattern, setValueHolder

Constructor Detail

DefaultSelectModel

public DefaultSelectModel()

Constructs a new DefaultSelectModel The default valueHolder for this model is a String VariantValueHolder. The default list for this model is an ObjectArrayValueHolder with an empty Object array.

DefaultSelectModel

public DefaultSelectModel(int javaDataType)
                   throws UnsupportedDataTypeException

Constructs new DefaultSelectModel and sets valueHolder to a VariantValueHolder for given data type. The default list for this model is an ObjectArrayValueHolder with an empty Object array.

Throws:

UnsupportedDataTypeException - if invalid javaDataType is given

See Also:

DataTypes

Method Detail

createDefaultList

protected CollectionValueHolder createDefaultList()

Constructs a default list for this model. The default list is an ObjectArrayValueHolder with an empty Object array.

getText

public java.lang.String getText()
                         throws ModelException

Returns display value of current selection.

Specified by:

getText in interface TextModel

Overrides:

getText in class DefaultTextModel

Returns:

the valueHolder's propertyValue as a formatted String

Throws:

NotInListException - if current valueHolder object values do not match any item in list.

ModelException - if problem while matching properties of valueHolder object to list object.

setText

public void setText(java.lang.String value)
             throws ModelException

Sets the current selection by matching the given value to the list's display values. This method also copies the corresponding values from the selected list object to the valueHolder object. If the given value is null or a value matching the nullDisplay, this model will set the propertyNames[] in the valueHolder object to null.

Specified by:

setText in interface TextModel

Overrides:

setText in class DefaultTextModel

Throws:

NotInListException - if the given value does not match any item in list.

ModelException - if problem while setting properties of object in valueHolder or fetching display values from the list.

getSelectedItem

public java.lang.Object getSelectedItem()
                                 throws ModelException

Returns the currently selected item from the list.

Specified by:

getSelectedItem in interface SelectModel

Throws:

NotInListException - if current valueHolder object values do not match any item in list.

ModelException - if problem while matching properties of valueHolder object to list object.

setSelectedItem

public void setSelectedItem(java.lang.Object value)
                     throws ModelException

Sets the current selection by searching through the list for the given object. This method also copies the corresponding values from the selected list object to the valueHolder object. If the given value is null or a value matching the nullDisplay, this model will set the propertyNames[] in the valueHolder object to null.

Specified by:

setSelectedItem in interface SelectModel

Throws:

NotInListException - if the given value does not match any item in list.

ModelException - if problem while setting properties of object in valueHolder or fetching display values from the list.

getDisplayOptionList

public java.util.Collection getDisplayOptionList()
                                          throws ModelException

Returns a Collection of the SelectModelOptions. The SelectModelOption has 2 properties: optionText which is the value to display in the list and selected, which indicates whether or not the item is selected.

The nullDisplay value will be first in the collection.

Specified by:

getDisplayOptionList in interface SelectModel

Throws:

ModelException - if problem while matching properties of valueHolder object to list object.

getCurrentPropertyValues

protected java.lang.String getCurrentPropertyValues()
                                             throws ModelException

Throws:

ModelException

isCurrentMatch

protected boolean isCurrentMatch()
                          throws ModelException

Compares the corresponding property values of the current list with valueHolder object.

Returns:

true if values match

Throws:

ModelException - if problem while accessing properties of valueHolder object or list object.

isValueNull

protected boolean isValueNull()
                       throws ModelException

Returns true if all of the properties (propertyNames[]) are null.

Throws:

ModelException - if problem accessing properties of valueHolder object.

copyValues

protected void copyValues()
                   throws ModelException

Copies the corresponding values from the current listObject to the valueHolder object.

Throws:

ModelException - if problem copying values

setNullValues

protected void setNullValues()
                      throws ModelException

Sets the propertyNames[] in the valueHolder object to null.

Throws:

ModelException - if problem occurs

createDefaultValueHolder

protected ValueHolder createDefaultValueHolder()

Creates an ObjectValueHolder as the default ValueHolder for model.

Overrides:

createDefaultValueHolder in class DefaultTextModel

Returns:

a new ValueHolder for this component to use.

setList

public void setList(CollectionValueHolder newList)

Sets collectionValueHolder which holds the collection of possible selections.

Specified by:

setList in interface SelectModel

getList

public CollectionValueHolder getList()

Returns collectionValueHolder which holds the collection of possible selections.

Specified by:

getList in interface SelectModel

setDisplayPropertyName

public void setDisplayPropertyName(java.lang.String newDisplayPropertyName)

Sets the property name of the list object to display in the list. Default is "value".

Specified by:

setDisplayPropertyName in interface SelectModel

getDisplayPropertyName

public java.lang.String getDisplayPropertyName()

Returns the property name of the list object to display in the list. Default is "value".

Specified by:

getDisplayPropertyName in interface SelectModel

setListPropertyNames

public void setListPropertyNames(java.lang.String[] newListPropertyNames)

Sets array of property names in list object to copy to valueHolder object. Default is {"value"}.

Specified by:

setListPropertyNames in interface SelectModel

getListPropertyNames

public java.lang.String[] getListPropertyNames()

Returns array of property names in list object to copy to valueHolder object. Default is {"value"}.

Specified by:

getListPropertyNames in interface SelectModel

setPropertyNames

public void setPropertyNames(java.lang.String[] newPropertyNames)

Sets array of property names in valueHolder object that correspond to properties of list object. Default is {"value"}.

Specified by:

setPropertyNames in interface SelectModel

getPropertyNames

public java.lang.String[] getPropertyNames()

Gets array of property names in valueHolder object that correspond to properties of list object. Default is {"value"}.

Specified by:

getPropertyNames in interface SelectModel

setPropertyName

public void setPropertyName(java.lang.String newPropertyName)

Sets the property name in valueHolder that will hold the value from the list. If you have also used the setPropertyNames method, then this will change the first name in that array.

Specified by:

setPropertyName in interface TextModel

Overrides:

setPropertyName in class DefaultTextModel

getPropertyName

public java.lang.String getPropertyName()

Gets the property name in valueHolder that will hold the value from the list. If you have also used the setPropertyNames method, then this will return the first name in that array.

Specified by:

getPropertyName in interface TextModel

Overrides:

getPropertyName in class DefaultTextModel

Returns:

the name of the property in the ValueHolder which holds the actual value.

setNullAllowed

public void setNullAllowed(boolean nullAllowed)

Sets indicator that a null value is a valid selection. If true, the nullDisplay value will appear in the list of options generated by getDisplayOptionList and setText will accept null or the nullDisplay value. If false, the setText method will throw a NotInListException if null or the nullDisplay value is set, and the nullDisplay will not appear in the displayOptionList. Default is true.

Specified by:

setNullAllowed in interface SelectModel

isNullAllowed

public boolean isNullAllowed()

Returns indicator that a null value is a valid selection. If true, the nullDisplay value will appear in the list of options generated by getDisplayOptionList and setText will accept null or the nullDisplay value. If false, the setText method will throw a NotInListException if null or the nullDisplay value is set, and the nullDisplay will not appear in the displayOptionList. Default is true.

Specified by:

isNullAllowed in interface SelectModel

setNullDisplay

public void setNullDisplay(java.lang.String newNullDisplay)

Sets value to display in list for a null value.

Specified by:

setNullDisplay in interface SelectModel

getNullDisplay

public java.lang.String getNullDisplay()

Returns value to display in list for a null value.

Specified by:

getNullDisplay in interface SelectModel

toString

public java.lang.String toString()

Returns a string representation of this object. This contains the object identity and state information.

Overrides:

toString in class DefaultTextModel

Returns:

a string representation of this object