Package jmri.implementation.decorators

Class AbstractNamedBeanDecorator

java.lang.Object

jmri.implementation.decorators.AbstractNamedBeanDecorator

All Implemented Interfaces:

Comparable<NamedBean>, PropertyChangeProvider, NamedBean

Direct Known Subclasses:

TimeoutReporter

public abstract class AbstractNamedBeanDecorator
extends Object
implements NamedBean

Abstract base for the NamedBean Decorators.

Nested Class Summary

Nested classes/interfaces inherited from interface jmri.NamedBean

NamedBean.BadNameException, NamedBean.BadSystemNameException, NamedBean.BadUserNameException, NamedBean.DisplayOptions, NamedBean.DuplicateSystemNameException

Field Summary

Fields

Modifier and Type	Field	Description
protected final HashMap<PropertyChangeListener,String>	listenerRefs
protected final HashMap<PropertyChangeListener,String>	register

Fields inherited from interface jmri.NamedBean

DISPLAY_NAME_FORMAT, INCONSISTENT, PROPERTY_COMMENT, PROPERTY_ENABLED, PROPERTY_KNOWN_STATE, PROPERTY_STATE, PROPERTY_USERNAME, QUOTED_NAME_FORMAT, UNKNOWN

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractNamedBeanDecorator(NamedBean decorated)

Method Summary

Modifier and Type	Method	Description
void	addPropertyChangeListener(PropertyChangeListener listener)	Add a PropertyChangeListener to the listener list.
void	addPropertyChangeListener(PropertyChangeListener l, String beanRef, String listenerRef)	Request a call-back when a bound property changes.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener)	Add a PropertyChangeListener for a specific property.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener l, String beanRef, String listenerRef)	Request a call-back when a bound property changes.
int	compareSystemNameSuffix(String suffix1, String suffix2, NamedBean n)	Compare the suffix of this NamedBean's name with the suffix of the argument NamedBean's name for the NamedBean.compareTo(jmri.NamedBean) operation.
String	describeState(int state)	Provide human-readable, localized version of state value.
void	dispose()	Deactivate this object, so that it releases as many resources as possible and no longer effects others.
boolean	equals(Object obj)
protected void	firePropertyChange(String p, Object old, Object n)
String	getBeanType()	For instances in the code where we are dealing with just a bean and a message needs to be passed to the user or in a log.
final String	getComment()	Get associated comment text.
final String	getDisplayName()	Get user name if it exists, otherwise return System name.
final String	getDisplayName(NamedBean.DisplayOptions displayOptions)	Get the name to display, formatted per NamedBean.DisplayOptions.
String	getListenerRef(PropertyChangeListener l)	Get the textual reference for the specific listener
ArrayList<String>	getListenerRefs()	Get a meaningful list of places where the bean is in use.
int	getNumPropertyChangeListeners()	Get the number of current listeners.
Object	getProperty(String key)	Retrieve the value associated with a key.
PropertyChangeListener[]	getPropertyChangeListeners()	Get all PropertyChangeListeners currently attached to this object.
PropertyChangeListener[]	getPropertyChangeListeners(String propertyName)	Get all PropertyChangeListeners currently listening to changes to the specified property.
PropertyChangeListener[]	getPropertyChangeListenersByReference(String name)	Get a list of all the property change listeners that are registered using a specific name
Set<String>	getPropertyKeys()	Retrieve the complete current set of keys.
final String	getSystemName()	Get a system-specific name.
final String	getUserName()	User's identification for the item.
int	hashCode()
void	removeProperty(String key)	Remove the key/value pair against the NamedBean.
void	removePropertyChangeListener(PropertyChangeListener listener)	Remove the specified listener from this object.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener)	Remove the specified listener of the specified property from this object.
final void	setComment(String comment)	Set associated comment text.
void	setProperty(String key, Object value)	Attach a key/value pair to the NamedBean, which can be retrieved later.
void	setUserName(String s)	Set the user name, normalizing it if needed.
final String	toString()	Display the system-specific name.
void	updateListenerRef(PropertyChangeListener l, String newName)
void	vetoableChange(PropertyChangeEvent evt)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface jmri.NamedBean

compareTo, getRecommendedToolTip, getState, getUsageReport, setState

Field Details

register

protected final HashMap<PropertyChangeListener,String> register

listenerRefs

protected final HashMap<PropertyChangeListener,String> listenerRefs

Constructor Details

AbstractNamedBeanDecorator

protected AbstractNamedBeanDecorator(NamedBean decorated)

Method Details

getComment

public final String getComment()

Get associated comment text.

Specified by:

getComment in interface NamedBean

Returns:

the comment or null

setComment

public final void setComment(String comment)

Set associated comment text.

Comments can be any valid text.

Specified by:

setComment in interface NamedBean

Parameters:

comment - the comment or null to remove an existing comment

getDisplayName

@CheckReturnValue
@Nonnull
public final String getDisplayName()

Get user name if it exists, otherwise return System name.

Specified by:

getDisplayName in interface NamedBean

Returns:

the user name or system-specific name

getDisplayName

@CheckReturnValue
@Nonnull
public final String getDisplayName(NamedBean.DisplayOptions displayOptions)

Get the name to display, formatted per NamedBean.DisplayOptions.

Specified by:

getDisplayName in interface NamedBean

Parameters:

displayOptions - the DisplayOptions to use

Returns:

the display name formatted per options

addPropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void addPropertyChangeListener(@Nonnull
 PropertyChangeListener l,
 String beanRef,
 String listenerRef)

Description copied from interface: NamedBean

Request a call-back when a bound property changes. Bound properties are the known state, commanded state, user and system names.

Specified by:

addPropertyChangeListener in interface NamedBean

Parameters:

l - The listener. This may change in the future to be a subclass of NamedProprtyChangeListener that carries the name and listenerRef values internally

beanRef - The name (either system or user) that the listener uses for this namedBean, this parameter is used to help determine when which listeners should be moved when the username is moved from one bean to another

listenerRef - A textual reference for the listener, that can be presented to the user when a delete is called

addPropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void addPropertyChangeListener(@Nonnull
 String propertyName,
 @Nonnull
 PropertyChangeListener l,
 String beanRef,
 String listenerRef)

Description copied from interface: NamedBean

Request a call-back when a bound property changes. Bound properties are the known state, commanded state, user and system names.

Specified by:

addPropertyChangeListener in interface NamedBean

Parameters:

propertyName - The name of the property to listen to

l - The listener. This may change in the future to be a subclass of NamedProprtyChangeListener that carries the name and listenerRef values internally

beanRef - The name (either system or user) that the listener uses for this namedBean, this parameter is used to help determine when which listeners should be moved when the username is moved from one bean to another

listenerRef - A textual reference for the listener, that can be presented to the user when a delete is called

addPropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void addPropertyChangeListener(PropertyChangeListener listener)

Description copied from interface: PropertyChangeProvider

Add a PropertyChangeListener to the listener list.

Specified by:

addPropertyChangeListener in interface PropertyChangeProvider

Parameters:

listener - The PropertyChangeListener to be added

addPropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void addPropertyChangeListener(String propertyName,
 PropertyChangeListener listener)

Description copied from interface: PropertyChangeProvider

Add a PropertyChangeListener for a specific property.

Specified by:

addPropertyChangeListener in interface PropertyChangeProvider

Parameters:

propertyName - The name of the property to listen on.

listener - The PropertyChangeListener to be added

removePropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void removePropertyChangeListener(PropertyChangeListener listener)

Description copied from interface: PropertyChangeProvider

Remove the specified listener from this object.

Specified by:

removePropertyChangeListener in interface PropertyChangeProvider

Parameters:

listener - The PropertyChangeListener to remove.

removePropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void removePropertyChangeListener(String propertyName,
 PropertyChangeListener listener)

Description copied from interface: PropertyChangeProvider

Remove the specified listener of the specified property from this object.

Specified by:

removePropertyChangeListener in interface PropertyChangeProvider

Parameters:

propertyName - The name of the property to stop listening to.

listener - The PropertyChangeListener to remove.

getPropertyChangeListenersByReference

@Nonnull
public PropertyChangeListener[] getPropertyChangeListenersByReference(@Nonnull
 String name)

Description copied from interface: NamedBean

Get a list of all the property change listeners that are registered using a specific name

Specified by:

getPropertyChangeListenersByReference in interface NamedBean

Parameters:

name - The name (either system or user) that the listener has registered as referencing this namedBean

Returns:

empty list if none

getListenerRefs

public ArrayList<String> getListenerRefs()

Get a meaningful list of places where the bean is in use.

Specified by:

getListenerRefs in interface NamedBean

Returns:

ArrayList of the listeners

updateListenerRef

@OverridingMethodsMustInvokeSuper
public void updateListenerRef(PropertyChangeListener l,
 String newName)

Specified by:

updateListenerRef in interface NamedBean

getListenerRef

public String getListenerRef(PropertyChangeListener l)

Description copied from interface: NamedBean

Get the textual reference for the specific listener

Specified by:

getListenerRef in interface NamedBean

Parameters:

l - the listener of interest

Returns:

the textual reference

getNumPropertyChangeListeners

public int getNumPropertyChangeListeners()

Get the number of current listeners.

Specified by:

getNumPropertyChangeListeners in interface NamedBean

Returns:

-1 if the information is not available for some reason.

getPropertyChangeListeners

@Nonnull
public PropertyChangeListener[] getPropertyChangeListeners()

Description copied from interface: PropertyChangeProvider

Get all PropertyChangeListeners currently attached to this object.

Specified by:

getPropertyChangeListeners in interface PropertyChangeProvider

Returns:

An array of PropertyChangeListeners.

getPropertyChangeListeners

@Nonnull
public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

Description copied from interface: PropertyChangeProvider

Get all PropertyChangeListeners currently listening to changes to the specified property.

Specified by:

getPropertyChangeListeners in interface PropertyChangeProvider

Parameters:

propertyName - the name of the property of interest

Returns:

an array of PropertyChangeListeners

getSystemName

@Nonnull
public final String getSystemName()

Get a system-specific name. This encodes the hardware addressing information. Any given system name must be unique within the layout.

Specified by:

getSystemName in interface NamedBean

Returns:

the system-specific name

toString

@Nonnull
public final String toString()

Display the system-specific name.

Note that this is a firm contract: toString() in all implementing classes must return the system name followed by optional additional information. Using code can assume that the result of toString() will always be or start with the system name followed by some kind of separator character.

Specified by:

toString in interface NamedBean

Overrides:

toString in class Object

Returns:

the system-specific name

getUserName

public final String getUserName()

Description copied from interface: NamedBean

User's identification for the item. Bound parameter so manager(s) can listen to changes. Any given user name must be unique within the layout. Must not match the system name.

Specified by:

getUserName in interface NamedBean

Returns:

null if not set

getBeanType

@Nonnull
public String getBeanType()

Description copied from interface: NamedBean

For instances in the code where we are dealing with just a bean and a message needs to be passed to the user or in a log.

Specified by:

getBeanType in interface NamedBean

Returns:

a string of the bean type, eg Turnout, Sensor etc

setUserName

@OverridingMethodsMustInvokeSuper
public void setUserName(String s)
                 throws NamedBean.BadUserNameException

Description copied from interface: NamedBean

Set the user name, normalizing it if needed.

Specified by:

setUserName in interface NamedBean

Parameters:

s - the new user name

Throws:

NamedBean.BadUserNameException - if the user name can not be normalized

firePropertyChange

@OverridingMethodsMustInvokeSuper
protected void firePropertyChange(String p,
 Object old,
 Object n)

dispose

@OverridingMethodsMustInvokeSuper
public void dispose()

Description copied from interface: NamedBean

Deactivate this object, so that it releases as many resources as possible and no longer effects others.

For example, if this object has listeners, after a call to this method it should no longer notify those listeners. Any native or system-wide resources it maintains should be released, including threads, files, etc.

It is an error to invoke any other methods on this object once dispose() has been called. Note, however, that there is no guarantee about behavior in that case.

Afterwards, references to this object may still exist elsewhere, preventing its garbage collection. But it's formally dead, and shouldn't be keeping any other objects alive. Therefore, this method should null out any references to other objects that this NamedBean contained.

Specified by:

dispose in interface NamedBean

describeState

@Nonnull
public String describeState(int state)

Description copied from interface: NamedBean

Provide human-readable, localized version of state value.

This method is intended for use when presenting to a human operator.

Specified by:

describeState in interface NamedBean

Parameters:

state - the state to describe

Returns:

the state in localized form

setProperty

@OverridingMethodsMustInvokeSuper
public void setProperty(@Nonnull
 String key,
 Object value)

Attach a key/value pair to the NamedBean, which can be retrieved later. These are not bound properties as yet, and don't throw events on modification. Key must not be null.

The key is constrained to String to make these behave like normal Java Beans.

Specified by:

setProperty in interface NamedBean

Parameters:

key - the property to set

value - the value of the property

getProperty

@OverridingMethodsMustInvokeSuper
public Object getProperty(@Nonnull
 String key)

Description copied from interface: NamedBean

Retrieve the value associated with a key. If no value has been set for that key, returns null.

Specified by:

getProperty in interface NamedBean

Parameters:

key - the property to get

Returns:

The value of the property or null.

getPropertyKeys

@OverridingMethodsMustInvokeSuper
@Nonnull
public Set<String> getPropertyKeys()

Description copied from interface: NamedBean

Retrieve the complete current set of keys.

Specified by:

getPropertyKeys in interface NamedBean

Returns:

empty set if none

removeProperty

@OverridingMethodsMustInvokeSuper
public void removeProperty(String key)

Description copied from interface: NamedBean

Remove the key/value pair against the NamedBean.

Specified by:

removeProperty in interface NamedBean

Parameters:

key - the property to remove

vetoableChange

public void vetoableChange(PropertyChangeEvent evt)
                    throws PropertyVetoException

Specified by:

vetoableChange in interface NamedBean

Throws:

PropertyVetoException

equals

public boolean equals(Object obj)

This implementation tests that NamedBean.getSystemName() is equal for this and obj.

Overrides:

equals in class Object

Parameters:

obj - the reference object with which to compare.

Returns:

true if this object is the same as the obj argument; false otherwise.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareSystemNameSuffix

@CheckReturnValue
public int compareSystemNameSuffix(@Nonnull
 String suffix1,
 @Nonnull
 String suffix2,
 @Nonnull
 NamedBean n)

Compare the suffix of this NamedBean's name with the suffix of the argument NamedBean's name for the NamedBean.compareTo(jmri.NamedBean) operation. This is intended to be a system-specific comparison that understands the various formats, etc.

Specified by:

compareSystemNameSuffix in interface NamedBean

Parameters:

suffix1 - The suffix for the 1st bean in the comparison

suffix2 - The suffix for the 2nd bean in the comparison

n - The other (second) NamedBean in the comparison

Returns:

-1,0,+1 for ordering if the names are well-formed; may not provide proper ordering if the names are not well-formed.