Package jmri.implementation

Class AbstractNamedBean

java.lang.Object

jmri.implementation.AbstractNamedBean

All Implemented Interfaces:

Comparable<NamedBean>, PropertyChangeProvider, NamedBean

Direct Known Subclasses:

AbstractAnalogIO, AbstractAudio, AbstractBase, AbstractIdTag, AbstractLight, AbstractMemory, AbstractNamedTable, AbstractReporter, AbstractSensor, AbstractSignalHead, AbstractSignalMast, AbstractStringIO, AbstractTurnout, Block, DefaultConditional, DefaultGlobalVariable, DefaultLogix, DefaultLogixNG, DefaultRoute, DefaultSection, DefaultSignalAppearanceMap, DefaultSignalGroup, DefaultSignalMastLogic, DefaultSignalSystem, DefaultTransit, DestinationPoints, LayoutBlock, SimpleTimebase, Warrant

public abstract class AbstractNamedBean
extends Object
implements NamedBean

Abstract base for the NamedBean interface.

Implements the parameter binding support.

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 String	mSystemName
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	AbstractNamedBean(String sys)	Create a new NamedBean instance using only a system name.
protected	AbstractNamedBean(String sys, String user)	Create a new NamedBean instance using both a system name and (optionally) a user name.

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)
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.
protected String	toStringSuffix()	Overload this in a sub-class to add extra info to the results of toString()
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, getBeanType, getRecommendedToolTip, getState, getUsageReport, setState

Field Details

mSystemName

protected final String mSystemName

register

protected final HashMap<PropertyChangeListener,String> register

listenerRefs

protected final HashMap<PropertyChangeListener,String> listenerRefs

Constructor Details

AbstractNamedBean

protected AbstractNamedBean(@Nonnull
 String sys)

Create a new NamedBean instance using only a system name.

Parameters:

sys - the system name for this bean; must not be null and must be unique within the layout

AbstractNamedBean

protected AbstractNamedBean(@Nonnull
 String sys,
 @CheckForNull
 String user)
                     throws NamedBean.BadUserNameException,
NamedBean.BadSystemNameException

Create a new NamedBean instance using both a system name and (optionally) a user name.

Refuses construction if unable to use the normalized user name, to prevent subclass from overriding setUserName(java.lang.String) during construction.

Parameters:

sys - the system name for this bean; must not be null

user - the user name for this bean; will be normalized if needed; can be null

Throws:

NamedBean.BadUserNameException - if the user name cannot be normalized

NamedBean.BadSystemNameException - if the system name is null

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)

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)

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)

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)

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)

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)

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)

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()

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)

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

toStringSuffix

protected String toStringSuffix()

Overload this in a sub-class to add extra info to the results of toString()

Returns:

a suffix to add at the end of #toString() result

getUserName

public final String getUserName()

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

setUserName

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

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()

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)

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)

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()

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)

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

Returns:

hash code value is based on the system name.

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. By default, does an alphanumeric-by-chunks comparison.

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.