org.jdesktop.binding.metadata
Class MetaData

java.lang.Object
  extended by org.jdesktop.binding.metadata.MetaData
Direct Known Subclasses:
EnumeratedMetaData, ListMetaData, NumberMetaData, SelectionInListMetaData, StringMetaData, TabularMetaData

public class MetaData
extends java.lang.Object

Class for representing the meta-data for an field in a data model. A "field" may map to a column on a RowSet, a property on a JavaBean, or some other discrete data element on a data model. The meta-data describes aspects of a data field such as it's name, type, and edit constraints. This class may be used when such information isn't encapsulated in the data model object itself and thus must be represented in an external object. Meta-data is intended only for holding state about a data model element and is not intended for implementing application semantics.

A meta-data object should be initialized at a minimum with a name, class, and label. Additional meta-data properties can be set as necessary. For example:


     MetaData metaData = new MetaData("firstname", String.class,
                                      "First Name");
     metaData.setRequired(true);
 
If the associated data model field requires application-specific validation logic to verify the correctness of a potential value, one or more Validator instances can be added to the meta-data object. Example:

     MetaData metaData = new MetaData("creditcard", String.class,
                                      "Credit Card Number"
     metaData.setRequired(true);
     metaData.addValidator(new MyCreditCardValidator());
 

Version:
1.0
Author:
Amy Fowler, Rich Bair

Field Summary
protected  Converter converter
           
protected  java.util.Map customProps
           
protected  java.lang.Object decodeFormat
           
protected  int displayWidth
           
protected  java.lang.Object encodeFormat
           
protected  java.lang.Class klass
           
protected  java.lang.String label
           
protected  int maxValueCount
           
protected  int minValueCount
           
protected  java.lang.String name
           
protected  java.beans.PropertyChangeSupport pcs
           
protected  boolean readOnly
           
protected  java.util.ArrayList validators
           
 
Constructor Summary
MetaData()
          Instantiates a meta-data object with a default name "value" and a default field class equal to java.lang.String.
MetaData(java.lang.String name)
          Instantiates a meta-data object with the specified name and a default field class equal to java.lang.String.
MetaData(java.lang.String name, java.lang.Class klass)
          Instantiates a meta-data object with the specified name and field class.
MetaData(java.lang.String name, java.lang.Class klass, java.lang.String label)
          Instantiates a meta-data object with the specified name, field class, and label.
 
Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener pcl)
          Adds the specified property change listener to this meta-data object.
 void addValidator(Validator validator)
          Adds the specified validator for this meta-data.
protected  void firePropertyChange(java.lang.String propertyName, boolean oldValue, boolean newValue)
           
protected  void firePropertyChange(java.lang.String propertyName, int oldValue, int newValue)
           
protected  void firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
           
 Converter getConverter()
          Gets the meta-data's converter, which performs conversions between string values and objects of the associated data field's type.
 java.lang.Object getCustomProperty(java.lang.String propertyName)
           
 java.lang.Object getCustomProperty(java.lang.String propertyName, java.lang.Object defaultValue)
           
 java.lang.String[] getCustomPropertyKeys()
           
 java.lang.Object getDecodeFormat()
          Gets the meta-data's decode format which is used when converting values from a string representation.
 int getDisplayWidth()
           
 java.lang.Class getElementClass()
          Gets the meta-data's "elementClass" property which indicates the type of the associated data field.
 java.lang.Object getEncodeFormat()
          Gets the meta-data's encode format which is used when converting values to a string representation.
 java.lang.String getLabel()
          Gets the meta-data's "label" property, which provides a label for the associated data field.
 int getMaxValueCount()
          Gets the meta-data's "maxValueCount" property, which indicates the maximum number of values permitted for the data field.
 int getMinValueCount()
          Gets the meta-data's "minValueCount" property, which indicates the minimum number of values required for the data field.
 java.lang.String getName()
          Gets the meta-data "name" property which indicates the logical name of the associated data field.
 java.beans.PropertyChangeListener[] getPropertyChangeListeners()
           
 Validator[] getValidators()
           
 boolean isReadOnly()
          Gets the meta-data's "readOnly" property which indicates whether or not the associated data field's value cannot be modified.
 boolean isRequired()
          Convenience method for calculating whether the "minValueCount" property is greater than 0.
 void removeCustomProperty(java.lang.String propertyName)
          Removes the custom property from the custom properties map.
 void removePropertyChangeListener(java.beans.PropertyChangeListener pcl)
          Removes the specified property change listener from this meta-data object.
 void removeValidator(Validator validator)
          Removes the specified validator for this meta-data.
 void setConverter(Converter converter)
          Sets the meta-data's converter.
 void setCustomProperty(java.lang.String propertyName, java.lang.Object value)
          Places a custom property into this meta-data's custom properties map.
 void setDecodeFormat(java.lang.Object format)
          Sets the meta-data's decode format which is used when converting values from a string representation.
 void setDisplayWidth(int displayWidth)
          Sets the meta-data's "displayWidth" property which provides a hint as to the number of characters typically required to display the value.
 void setElementClass(java.lang.Class klass)
          Sets the meta-data's "elementClass" property.
 void setEncodeFormat(java.lang.Object format)
          Sets the meta-data's encode format which is used when converting values to a string representation.
 void setLabel(java.lang.String label)
          Sets the meta-data's "label" property.
 void setMaxValueCount(int maxValueCount)
          Sets the meta-data's "maxValueCount" property.
 void setMinValueCount(int minValueCount)
          Sets the meta-data's "minValueCount" property.
 void setName(java.lang.String name)
          Sets the meta-data "name" property.
 void setReadOnly(boolean readOnly)
          Sets the meta-data's "readOnly" property.
 void setRequired(boolean required)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

name

protected java.lang.String name

klass

protected java.lang.Class klass

label

protected java.lang.String label

converter

protected Converter converter

decodeFormat

protected java.lang.Object decodeFormat

encodeFormat

protected java.lang.Object encodeFormat

readOnly

protected boolean readOnly

minValueCount

protected int minValueCount

maxValueCount

protected int maxValueCount

displayWidth

protected int displayWidth

validators

protected java.util.ArrayList validators

customProps

protected java.util.Map customProps

pcs

protected java.beans.PropertyChangeSupport pcs
Constructor Detail

MetaData

public MetaData()
Instantiates a meta-data object with a default name "value" and a default field class equal to java.lang.String. This provides the no-argument constructor required for JavaBeans. It is recommended that the program explicitly set a meaningful "name" property.


MetaData

public MetaData(java.lang.String name)
Instantiates a meta-data object with the specified name and a default field class equal to java.lang.String.

Parameters:
name - String containing the name of the data field

MetaData

public MetaData(java.lang.String name,
                java.lang.Class klass)
Instantiates a meta-data object with the specified name and field class.

Parameters:
name - String containing the name of the data field
klass - Class indicating type of data field

MetaData

public MetaData(java.lang.String name,
                java.lang.Class klass,
                java.lang.String label)
Instantiates a meta-data object with the specified name, field class, and label.

Parameters:
name - String containing the name of the data field
klass - Class indicating type of data field
label - String containing the user-displayable label for the data field
Method Detail

getName

public java.lang.String getName()
Gets the meta-data "name" property which indicates the logical name of the associated data field.

Returns:
String containing the name of the data field.
See Also:
setName(java.lang.String)

setName

public void setName(java.lang.String name)
Sets the meta-data "name" property.

Parameters:
name - String containing the name of the data field
See Also:
getName()

getElementClass

public java.lang.Class getElementClass()
Gets the meta-data's "elementClass" property which indicates the type of the associated data field. The default field class is java.lang.String.

Returns:
Class indicating type of data field
See Also:
setElementClass(java.lang.Class)

setElementClass

public void setElementClass(java.lang.Class klass)
Sets the meta-data's "elementClass" property. This set method is provided for meta-data bean initialization only; the field class is not intended to be modified after initialization, since other aspects of a meta-data object may depend on this type setting.

Parameters:
klass - Class indicating type of data field
See Also:
getElementClass()

getLabel

public java.lang.String getLabel()
Gets the meta-data's "label" property, which provides a label for the associated data field. The label is intended for display to the end-user and may be localized. If no label has been explicitly set, then the meta-data's name is returned.

Returns:
String containing the user-displayable label for the data field
See Also:
setLabel(java.lang.String)

setLabel

public void setLabel(java.lang.String label)
Sets the meta-data's "label" property.

Parameters:
label - String containing the user-displable label for the data field
See Also:
getLabel()

getConverter

public Converter getConverter()
Gets the meta-data's converter, which performs conversions between string values and objects of the associated data field's type. If no converter was explicitly set on this meta-data object, this method will retrieve a default converter for this data field's type from the converter registry. If no default converter is registered, this method will return null.

Returns:
Converter used to perform conversions between string values and objects of this field's type
See Also:
Converters.get(java.lang.Class), setConverter(org.jdesktop.binding.metadata.Converter), getElementClass()

setConverter

public void setConverter(Converter converter)
Sets the meta-data's converter.

Parameters:
converter - Converter used to perform conversions between string values and objects of this field's type
See Also:
getConverter()

getDecodeFormat

public java.lang.Object getDecodeFormat()
Gets the meta-data's decode format which is used when converting values from a string representation. This property must be used when conversion requires format information on how the string representation is structured. For example, a decode format should be used when decoding date values. The default decode format is null.

Returns:
format object used to describe format for string-to-object conversion
See Also:
setDecodeFormat(java.lang.Object)

setDecodeFormat

public void setDecodeFormat(java.lang.Object format)
Sets the meta-data's decode format which is used when converting values from a string representation.

Parameters:
format - object used to describe format for string-to-object conversion
See Also:
getDecodeFormat(), DateFormat

getEncodeFormat

public java.lang.Object getEncodeFormat()
Gets the meta-data's encode format which is used when converting values to a string representation. This property must be used when conversion requires format information on how the string representation should be generated. For example, an encode format should be used when encoding date values. The default encode format is null.

Returns:
format object used to describe format for object-to-string conversion
See Also:
setEncodeFormat(java.lang.Object)

setEncodeFormat

public void setEncodeFormat(java.lang.Object format)
Sets the meta-data's encode format which is used when converting values to a string representation.

Parameters:
format - object used to describe format for object-to-string conversion
See Also:
getEncodeFormat(), DateFormat

getDisplayWidth

public int getDisplayWidth()
Returns:
integer containing the number of characters required to display the value

setDisplayWidth

public void setDisplayWidth(int displayWidth)
Sets the meta-data's "displayWidth" property which provides a hint as to the number of characters typically required to display the value. The default is 24.

Parameters:
displayWidth - integer containing the number of characters required to display the value
Throws:
java.lang.IllegalArgumentException - if displayWidth < 0
See Also:
getDisplayWidth()

isReadOnly

public boolean isReadOnly()
Gets the meta-data's "readOnly" property which indicates whether or not the associated data field's value cannot be modified. The default is false.

Returns:
boolean indicating whether the data field is read-only
See Also:
setReadOnly(boolean)

setReadOnly

public void setReadOnly(boolean readOnly)
Sets the meta-data's "readOnly" property.

Parameters:
readOnly - boolean indicating whether the data field is read-only
See Also:
isReadOnly()

getMinValueCount

public int getMinValueCount()
Gets the meta-data's "minValueCount" property, which indicates the minimum number of values required for the data field. The default is 0, which means a null value is permitted. This property should be set to 1 if the field requires a non-null value.

Returns:
integer indicating the minimum number of values required for the data field
See Also:
setMinValueCount(int)

setMinValueCount

public void setMinValueCount(int minValueCount)
Sets the meta-data's "minValueCount" property.

Parameters:
minValueCount - integer indicating the minimum number of values required for the data field

isRequired

public boolean isRequired()
Convenience method for calculating whether the "minValueCount" property is greater than 0.

Returns:
boolean indicating whether at least one non-null value must be set for the data field

setRequired

public void setRequired(boolean required)

getMaxValueCount

public int getMaxValueCount()
Gets the meta-data's "maxValueCount" property, which indicates the maximum number of values permitted for the data field. The default is 1, which means a single value is permitted. If this property is set to a value greater than 1, then the values will be contained in a List collection.

Returns:
integer indicating the maximum number of values permitted for the data field
See Also:
List, setMaxValueCount(int)

setMaxValueCount

public void setMaxValueCount(int maxValueCount)
Sets the meta-data's "maxValueCount" property.

Parameters:
maxValueCount - integer indicating the maximum number of values permitted for the data field

setCustomProperty

public void setCustomProperty(java.lang.String propertyName,
                              java.lang.Object value)
Places a custom property into this meta-data's custom properties map.

Parameters:
propertyName - A non-null string of the form com.mydomain.packagename.PropertyName
value - The value for the named property

getCustomProperty

public java.lang.Object getCustomProperty(java.lang.String propertyName)
Parameters:
propertyName - A non-null string of the form com.mydomain.packagename.PropertyName
Returns:
The value for the given propertyName in the custom properties map.

getCustomProperty

public java.lang.Object getCustomProperty(java.lang.String propertyName,
                                          java.lang.Object defaultValue)
Parameters:
propertyName - A non-null string of the form com.mydomain.packagename.PropertyName
defaultValue - The default value to return if the custom properties map does not contain they specified propertyName
Returns:
The value at the given propertyName in the customProps map.

removeCustomProperty

public void removeCustomProperty(java.lang.String propertyName)
Removes the custom property from the custom properties map.

Parameters:
propertyName - A non-null string of the form com.mydomain.packagename.PropertyName

getCustomPropertyKeys

public java.lang.String[] getCustomPropertyKeys()
Returns:
array containing the existing propertyNames in the custom properties map.

addValidator

public void addValidator(Validator validator)
Adds the specified validator for this meta-data. A validator object is used to determine whether a particular object is a valid value for the associated data field. A data field may have 0 or more validators.

Parameters:
validator - Validator object which performs validation checks on values being set on the associated data field
See Also:
removeValidator(org.jdesktop.binding.metadata.Validator), getValidators()

removeValidator

public void removeValidator(Validator validator)
Removes the specified validator for this meta-data.

Parameters:
validator - Validator object which performs validation checks on values being set on the associated data field
See Also:
addValidator(org.jdesktop.binding.metadata.Validator)

getValidators

public Validator[] getValidators()
Returns:
array containing 0 or more validators set on this meta-data
See Also:
addValidator(org.jdesktop.binding.metadata.Validator)

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener pcl)
Adds the specified property change listener to this meta-data object.

Parameters:
pcl - PropertyChangeListener object to receive events when meta-data properties change

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener pcl)
Removes the specified property change listener from this meta-data object.

Parameters:
pcl - PropertyChangeListener object to receive events when meta-data properties change

getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners()
Returns:
array containing the PropertyChangeListener objects registered on this meta-data object

firePropertyChange

protected void firePropertyChange(java.lang.String propertyName,
                                  int oldValue,
                                  int newValue)

firePropertyChange

protected void firePropertyChange(java.lang.String propertyName,
                                  boolean oldValue,
                                  boolean newValue)

firePropertyChange

protected void firePropertyChange(java.lang.String propertyName,
                                  java.lang.Object oldValue,
                                  java.lang.Object newValue)


Copyright © 2005 Sun Microsystems All Rights Reserved.