cern.gp.beans

Class BeanSupport

java.lang.Object

cern.gp.beans.BeanSupport

All Implemented Interfaces:

GPBean

Direct Known Subclasses:

SimpleDemoBean

public class BeanSupport
extends java.lang.Object
implements GPBean

This support class should be subclassed by bean classes. It facilitates the writing of JavaBean classes that are friendly with a node representing them by providing the extra information needed. The information provided by the bean can be static or dynamic using PropertyChangeEvents.

This support class provides the necessary methods to register a listener and provides methods to send PropertyChangeEvents. The bean can use the protected methods to fire events each time a property changes.

In order to be represented by a node, the bean can provide extra information that is not directly related to the business of the bean but that is nevertheless interesting to control the node. The bean can provide that information through its BeanInfo or through specific getters (defined in the interface GPNode). The information provided can be static or dynamic. It is static if the value is just given once when the node is created, it is dynamic if the bean allow the node to register itself as PropertyChangeListener and fire events when those properties changes.

The list of properties recognized by the node and associated getters is given by the GPBean interface. This support class implements all the getter methods in GPNode by returning a null value. You should override each method you want to provide information for. For each property that can be dynamically updated there is a protected method in this class you can use to fire an event to update the value. Here is the list :

property name	method name	method to fire related event
name	getName()	fireNamePropertyChange()
displayName	getDisplayName()	fireDisplayNamePropertyChange()
shortDescription	getShortDescription()	fireShortDescriptionPropertyChange()
nodeDefaultAction	getNodeDefaultAction()	fireNodeDefaultActionPropertyChange()
nodeIcon	getNodeIcon	fireNodeIconPropertyChange()

If the bean fire a given event, it should provide the getter matching the PropertyChangeEvent that it fires. For instance if the bean call the protected method fireNamePropertyChange when a name change occurs, it should have the matching getter getName() implemented and returning a non null value.

When a given getter is not available in this bean, the corresponding information will be looked-up in the BeanInfo. It will only be static, because the BeanInfo provides static information common to all beans. There is only one BeanInfo for a given class of beans and therefore the information founds inside the BeanInfo is shared by all beans of that class. If the BeanInfo does not contain the information, a standard default value will be applied when possible.

Author:

Lionel Mestre

Field Summary

Fields inherited from interface cern.gp.beans.GPBean

CLASS_PROPERTY_NAME, DISPLAYNAME_PROPERTY_DISPLAY_NAME, DISPLAYNAME_PROPERTY_NAME, NAME_PROPERTY_DISPLAY_NAME, NAME_PROPERTY_NAME, NODE_ACTIONS_PROPERTY_NAME, NODE_DEFAULT_ACTION_PROPERTY_NAME, NODE_ICON_PROPERTY_NAME, NODE_PROPERTIES_CACHEABLE_PROPERTY_NAME, PROPERTY_INFO_PROPERTY_NAME, SHORTDESCRIPTION_PROPERTY_DISPLAY_NAME, SHORTDESCRIPTION_PROPERTY_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BeanSupport()

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a PropertyChangeListener to the listener list.
void	addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Remove a PropertyChangeListener from the listener list.
protected void	checkPropertyChangeSupport() Lazily creates the PropertyChangeSupport
protected void	fireDisplayNamePropertyChange(java.lang.String newDisplayName) Reports a DisplayName property update to any registered listeners.
protected void	fireNamePropertyChange(java.lang.String newName) Reports a Name property update to any registered listeners.
protected void	fireNodeDefaultActionPropertyChange(java.lang.String newDefaultAction) Reports a default action property update to any registered listeners.
protected void	fireNodeIconPropertyChange(java.awt.Image newIcon) Reports a icon property update to any registered listeners.
protected void	firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue) Reports a bound property update to any registered listeners.
protected void	fireShortDescriptionPropertyChange(java.lang.String newShortDescription) Reports a ShortDescription property update to any registered listeners.
java.lang.String	getDisplayName() Returns the internal display name of the associated bean.
java.lang.String	getName() Returns the internal name of the associated bean.
java.lang.String[]	getNodeActions() Returns an array of qualified name of actions for the node representing the associated bean.
java.lang.String	getNodeDefaultAction() Returns the qualified name of the default action for the node representing the associated bean.
java.awt.Image	getNodeIcon() Returns the icon in 16x16 size used to display the node representing the associated bean.
protected java.awt.Image	getNodeIconFromPathname(java.lang.String newIconPathname) Returns the icon image from the pathname of the icon.
java.lang.Boolean	getNodePropertiesCacheable() Returns true if the value of the properties can be cached in the node, false if they cannot or null if no behavior is specified.
PropertyInfo[]	getPropertyInfo() Returns an array of PropertyInfo specifying information on some properties.
java.lang.String	getShortDescription() Returns a short description of the associated bean (used in tooltip for instance).
protected static java.lang.String[]	mergeNodeActions(java.lang.String[] actions1, java.lang.String[] actions2) Merges the two String arrays into one.
protected static PropertyInfo[]	mergePropertyInfo(PropertyInfo[] info1, PropertyInfo[] info2) Merges the two PropertyInfo arrays into one.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Add a PropertyChangeListener for a specific property.
void	removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Remove a PropertyChangeListener for a specific property.

Methods inherited from class java.lang.Object

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

Constructor Detail

BeanSupport

protected BeanSupport()

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a PropertyChangeListener to the listener list. The listener is registered for all properties.

Parameters:

listener - The PropertyChangeListener to be added

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)

Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Parameters:

listener - The PropertyChangeListener to be removed

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a PropertyChangeListener for a specific property. The listener will be invoked only when a call on firePropertyChange names that specific property.

Parameters:

propertyName - The name of the property to listen on.

listener - The PropertyChangeListener to be added

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)

Remove a PropertyChangeListener for a specific property.

Parameters:

propertyName - The name of the property that was listened on.

listener - The PropertyChangeListener to be removed

getDisplayName

public java.lang.String getDisplayName()

Description copied from interface: GPBean

Returns the internal display name of the associated bean. If null is returned a default name will be used.

• Property name : displayName
• Visibility : normal (visible in a property sheet)
• Default value (when null is returned from this method) : if getName() is available it is used instead of getDisplayName(), else beanInfo.getBeanDescriptor().getDisplayName() is used

Specified by:

getDisplayName in interface GPBean

Returns:

the internal display name of the associated bean or null

getName

public java.lang.String getName()

Description copied from interface: GPBean

Returns the internal name of the associated bean. If null is returned a default name will be used.

• Property name : name
• Visibility : normal (visible in a property sheet)
• Default value (when null is returned from this method) : a unique name generated using BeanUtils. generateUniqueBeanName()

Specified by:

getName in interface GPBean

Returns:

the internal name of the associated bean or null.

getNodeActions

public java.lang.String[] getNodeActions()

Description copied from interface: GPBean

Returns an array of qualified name of actions for the node representing the associated bean. Null can be used in the array to represent a separator.

• Property name : nodeActions
• Visibility : hidden (not visible in a property sheet)
• Default value (when null is returned from this method) : use the possible tagging of the BeanDescriptor of the BeanInfo : BeanTagger.getActions(beanInfo.getBeanDescriptor())

Specified by:

getNodeActions in interface GPBean

Returns:

an array of qualified name of actions for a node representing the bean.

getNodeDefaultAction

public java.lang.String getNodeDefaultAction()

Description copied from interface: GPBean

Returns the qualified name of the default action for the node representing the associated bean. The default action is the one triggered when the user double-clic on the node. If null is returned a default default action will be used.

• Property name : nodeDefaultAction
• Visibility : hidden
• Default value (when null is returned from this method) : use the possible tagging of the BeanDescriptor of the BeanInfo : BeanTagger.getDefaultAction(beanInfo.getBeanDescriptor())

Specified by:

getNodeDefaultAction in interface GPBean

Returns:

the qualified name of the default action for the node or null representing the associated bean.

getNodeIcon

public java.awt.Image getNodeIcon()

Description copied from interface: GPBean

Returns the icon in 16x16 size used to display the node representing the associated bean. If null is returned a default icon will be used.

• Property name : nodeIcon
• Visibility : hidden (not visible in a property sheet)
• Default value (when null is returned from this method) : beanInfo.getIcon()

Specified by:

getNodeIcon in interface GPBean

Returns:

the icon in 16x16 size used to display the node representing the associated bean or null

getNodePropertiesCacheable

public java.lang.Boolean getNodePropertiesCacheable()

Description copied from interface: GPBean

Returns true if the value of the properties can be cached in the node, false if they cannot or null if no behavior is specified. The default behavior is not to cache the value of the properties.

If the value of a property is not cached, the getter method will be invoked whenever the node need to get the value of the property.

If the value of the property is cached, the getter method for the property will only be invoked once to read the value. Then, whenever the node need the value of the property it will used the cached one until a PropertyChangeEvent for the property (or for all properties) is fired.

Caching values can improve performance greatly but it adds one more responsibility on the developer who has to fire PropertyChangeEvent whenever the property values change.

This property gives the caching strategy for all properties. It is possible to override the bean level caching strategy at the property level by using the property information getPropertyInformation().

• Property name : nodePropertiesCacheable
• Visibility : hidden (not visible in a property sheet)
• Default value (when null is returned from this method) : use the possible tagging of the BeanDescriptor of the BeanInfo : BeanTagger.isCacheable(beanInfo.getBeanDescriptor())

Specified by:

getNodePropertiesCacheable in interface GPBean

Returns:

true is the value of the properties can be cached in the node, false else or null for default behavior

getShortDescription

public java.lang.String getShortDescription()

Description copied from interface: GPBean

Returns a short description of the associated bean (used in tooltip for instance). If null is returned a default description will be used.

• Property name : shortDescription
• Visibility : normal (visible in a property sheet)
• Default value (when null is returned from this method) : beanInfo.getBeanDescriptor(). getShortDescription()

Specified by:

getShortDescription in interface GPBean

Returns:

a short description of the associated bean or null

getPropertyInfo

public PropertyInfo[] getPropertyInfo()

Description copied from interface: GPBean

Returns an array of PropertyInfo specifying information on some properties.

Each PropertyInfo of this array defines information for one property of this bean. Defining a PropertyInfo for a given property is usefull when there is no explicit BeanInfo for the bean and when the property have non default characteristics such as, for instance, a specific PropertyEditor.

• Property name : propertyInfo
• Visibility : hidden (not visible in a property sheet)
• Default value (when null is returned from this method) : use PropertyDescriptors from BeanInfo

Specified by:

getPropertyInfo in interface GPBean

Returns:

true is the value of the properties can be cached in the node, false else or null for default behavior

firePropertyChange

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

Reports a bound property update to any registered listeners. No event is fired if old and new are equal and non-null. You pass null for all 3 parameters, to tell the listeners to read all properties again, using the accessor methods. This is useful if you want to force all properties of this bean to be refreshed in the GUI (e.g. refresh the whole property sheet or a row in a ListTable at once).

Parameters:

propertyName - The programmatic name of the property that was changed.

oldValue - The old value of the property.

newValue - The new value of the property.

fireNamePropertyChange

protected void fireNamePropertyChange(java.lang.String newName)

Reports a Name property update to any registered listeners.

Parameters:

newName - The new value of the name.

fireDisplayNamePropertyChange

protected void fireDisplayNamePropertyChange(java.lang.String newDisplayName)

Reports a DisplayName property update to any registered listeners.

Parameters:

newDisplayName - The new value of the DisplayName.

fireShortDescriptionPropertyChange

protected void fireShortDescriptionPropertyChange(java.lang.String newShortDescription)

Reports a ShortDescription property update to any registered listeners.

Parameters:

newShortDescription - The new value of the ShortDescription.

fireNodeIconPropertyChange

protected void fireNodeIconPropertyChange(java.awt.Image newIcon)

Reports a icon property update to any registered listeners.

Parameters:

newIcon - The new value of the icon.

See Also:

getNodeIconFromPathname(String)

fireNodeDefaultActionPropertyChange

protected void fireNodeDefaultActionPropertyChange(java.lang.String newDefaultAction)

Reports a default action property update to any registered listeners.

Parameters:

newDefaultAction - The new value of the default action.

getNodeIconFromPathname

protected java.awt.Image getNodeIconFromPathname(java.lang.String newIconPathname)

Returns the icon image from the pathname of the icon.

The pathname should be relative to the package of this bean and be contained in the classpath. For instance if this bean is in cern.gp.beans and the icon is stored in cern/gp/beans/images/MyIcon.gif the pathname to give would be images/MyIcon.gif.

Parameters:

newIconPathname - The new value of the Icon pathname.

Returns:

the image defined by the icon pathname or null if it cannot be found or loaded.

mergeNodeActions

protected static java.lang.String[] mergeNodeActions(java.lang.String[] actions1,
                                                     java.lang.String[] actions2)

Merges the two String arrays into one. This method is useful when a class inherits from another that already has a method getNodeActions that returned an array of String. If the subclass wants to return a String array while taking into account the one from the parent class it can use this method. For instance :

 String[] parentArray= super.getNodeActions(); 
 String[] myArray = new String [] { .... }; 
 return mergePropertyInfo(parentPI, myPI);
 

Parameters:

actions1 - the first array of String to merge

actions2 - the second array of String to merge

Returns:

String[] the array resulting of the merging of the two given array

mergePropertyInfo

protected static PropertyInfo[] mergePropertyInfo(PropertyInfo[] info1,
                                                  PropertyInfo[] info2)

Merges the two PropertyInfo arrays into one. This method is useful when a class inherits from another that already has a method getPropertyInfo that returned an array of PropertyInfo. If the subclass wants to return PropertyInfo while taking into account the one from the parent class it can use this method. For instance :

   PropertyInfo[] parentPI = super.getPropertyInfo();
   PropertyInfo[] myPI = new PropertyInfo[] { .... };
   return mergePropertyInfo(parentPI, myPI);
 

Parameters:

info1 - the first array of PropertyInfo to merge

info2 - the second array of PropertyInfo to merge

Returns:

PropertyInfo[] the array resulting of the merging of the two given array

checkPropertyChangeSupport

protected void checkPropertyChangeSupport()

Lazily creates the PropertyChangeSupport