Class AbstractNamedBean
- java.lang.Object
-
- jmri.implementation.AbstractNamedBean
-
- All Implemented Interfaces:
java.lang.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 java.lang.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 java.util.HashMap<java.beans.PropertyChangeListener,java.lang.String>
listenerRefs
protected java.lang.String
mSystemName
protected java.util.HashMap<java.beans.PropertyChangeListener,java.lang.String>
register
-
Fields inherited from interface jmri.NamedBean
DISPLAY_NAME_FORMAT, INCONSISTENT, PROPERTY_STATE, QUOTED_NAME_FORMAT, UNKNOWN
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
AbstractNamedBean(java.lang.String sys)
Create a new NamedBean instance using only a system name.protected
AbstractNamedBean(java.lang.String sys, java.lang.String user)
Create a new NamedBean instance using both a system name and (optionally) a user name.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Add aPropertyChangeListener
to the listener list.void
addPropertyChangeListener(java.beans.PropertyChangeListener l, java.lang.String beanRef, java.lang.String listenerRef)
Request a call-back when a bound property changes.void
addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
Add aPropertyChangeListener
for a specific property.void
addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener l, java.lang.String beanRef, java.lang.String listenerRef)
Request a call-back when a bound property changes.int
compareSystemNameSuffix(java.lang.String suffix1, java.lang.String suffix2, NamedBean n)
Compare the suffix of this NamedBean's name with the suffix of the argument NamedBean's name for theNamedBean.compareTo(jmri.NamedBean)
operation.java.lang.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(java.lang.Object obj)
protected void
firePropertyChange(java.lang.String p, java.lang.Object old, java.lang.Object n)
java.lang.String
getComment()
Get associated comment text.java.lang.String
getDisplayName()
Get user name if it exists, otherwise return System name.java.lang.String
getDisplayName(NamedBean.DisplayOptions displayOptions)
Get the name to display, formatted perNamedBean.DisplayOptions
.java.lang.String
getListenerRef(java.beans.PropertyChangeListener l)
Get the textual reference for the specific listenerjava.util.ArrayList<java.lang.String>
getListenerRefs()
Get a meaningful list of places where the bean is in use.int
getNumPropertyChangeListeners()
Get the number of current listeners.java.lang.Object
getProperty(java.lang.String key)
Retrieve the value associated with a key.java.beans.PropertyChangeListener[]
getPropertyChangeListeners()
Get allPropertyChangeListener
s currently attached to this object.java.beans.PropertyChangeListener[]
getPropertyChangeListeners(java.lang.String propertyName)
Get allPropertyChangeListener
s currently listening to changes to the specified property.java.beans.PropertyChangeListener[]
getPropertyChangeListenersByReference(java.lang.String name)
Get a list of all the property change listeners that are registered using a specific namejava.util.Set<java.lang.String>
getPropertyKeys()
Retrieve the complete current set of keys.java.lang.String
getSystemName()
Get a system-specific name.java.lang.String
getUserName()
User's identification for the item.int
hashCode()
void
removeProperty(java.lang.String key)
Remove the key/value pair against the NamedBean.void
removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Remove the specified listener from this object.void
removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
Remove the specified listener of the specified property from this object.void
setComment(java.lang.String comment)
Set associated comment text.void
setProperty(java.lang.String key, java.lang.Object value)
Attach a key/value pair to the NamedBean, which can be retrieved later.void
setUserName(java.lang.String s)
Set the user name, normalizing it if needed.java.lang.String
toString()
Display the system-specific name.protected java.lang.String
toStringSuffix()
Overload this in a sub-class to add extra info to the results of toString()void
updateListenerRef(java.beans.PropertyChangeListener l, java.lang.String newName)
void
vetoableChange(java.beans.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, getState, getUsageReport, setState
-
-
-
-
Field Detail
-
mSystemName
protected final java.lang.String mSystemName
-
register
protected final java.util.HashMap<java.beans.PropertyChangeListener,java.lang.String> register
-
listenerRefs
protected final java.util.HashMap<java.beans.PropertyChangeListener,java.lang.String> listenerRefs
-
-
Constructor Detail
-
AbstractNamedBean
protected AbstractNamedBean(@Nonnull java.lang.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 java.lang.String sys, @CheckForNull java.lang.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 nulluser
- the user name for this bean; will be normalized if needed; can be null- Throws:
NamedBean.BadUserNameException
- if the user name cannot be normalizedNamedBean.BadSystemNameException
- if the system name is null
-
-
Method Detail
-
getComment
public final java.lang.String getComment()
Get associated comment text.- Specified by:
getComment
in interfaceNamedBean
- Returns:
- the comment or null
-
setComment
public final void setComment(java.lang.String comment)
Set associated comment text.Comments can be any valid text.
- Specified by:
setComment
in interfaceNamedBean
- Parameters:
comment
- the comment or null to remove an existing comment
-
getDisplayName
@CheckReturnValue @Nonnull public final java.lang.String getDisplayName()
Get user name if it exists, otherwise return System name.- Specified by:
getDisplayName
in interfaceNamedBean
- Returns:
- the user name or system-specific name
-
getDisplayName
@CheckReturnValue @Nonnull public final java.lang.String getDisplayName(NamedBean.DisplayOptions displayOptions)
Get the name to display, formatted perNamedBean.DisplayOptions
.- Specified by:
getDisplayName
in interfaceNamedBean
- Parameters:
displayOptions
- the DisplayOptions to use- Returns:
- the display name formatted per options
-
addPropertyChangeListener
@OverridingMethodsMustInvokeSuper public void addPropertyChangeListener(@Nonnull java.beans.PropertyChangeListener l, java.lang.String beanRef, java.lang.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 interfaceNamedBean
- Parameters:
l
- The listener. This may change in the future to be a subclass of NamedProprtyChangeListener that carries the name and listenerRef values internallybeanRef
- 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 anotherlistenerRef
- A textual reference for the listener, that can be presented to the user when a delete is called
-
addPropertyChangeListener
@OverridingMethodsMustInvokeSuper public void addPropertyChangeListener(@Nonnull java.lang.String propertyName, @Nonnull java.beans.PropertyChangeListener l, java.lang.String beanRef, java.lang.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 interfaceNamedBean
- Parameters:
propertyName
- The name of the property to listen tol
- The listener. This may change in the future to be a subclass of NamedProprtyChangeListener that carries the name and listenerRef values internallybeanRef
- 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 anotherlistenerRef
- A textual reference for the listener, that can be presented to the user when a delete is called
-
addPropertyChangeListener
@OverridingMethodsMustInvokeSuper public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Add aPropertyChangeListener
to the listener list.- Specified by:
addPropertyChangeListener
in interfacePropertyChangeProvider
- Parameters:
listener
- The PropertyChangeListener to be added
-
addPropertyChangeListener
@OverridingMethodsMustInvokeSuper public void addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
Add aPropertyChangeListener
for a specific property.- Specified by:
addPropertyChangeListener
in interfacePropertyChangeProvider
- Parameters:
propertyName
- The name of the property to listen on.listener
- The PropertyChangeListener to be added
-
removePropertyChangeListener
@OverridingMethodsMustInvokeSuper public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Remove the specified listener from this object.- Specified by:
removePropertyChangeListener
in interfacePropertyChangeProvider
- Parameters:
listener
- ThePropertyChangeListener
to remove.
-
removePropertyChangeListener
@OverridingMethodsMustInvokeSuper public void removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
Remove the specified listener of the specified property from this object.- Specified by:
removePropertyChangeListener
in interfacePropertyChangeProvider
- Parameters:
propertyName
- The name of the property to stop listening to.listener
- ThePropertyChangeListener
to remove.
-
getPropertyChangeListenersByReference
@Nonnull public java.beans.PropertyChangeListener[] getPropertyChangeListenersByReference(@Nonnull java.lang.String name)
Get a list of all the property change listeners that are registered using a specific name- Specified by:
getPropertyChangeListenersByReference
in interfaceNamedBean
- Parameters:
name
- The name (either system or user) that the listener has registered as referencing this namedBean- Returns:
- empty list if none
-
getListenerRefs
public java.util.ArrayList<java.lang.String> getListenerRefs()
Get a meaningful list of places where the bean is in use.- Specified by:
getListenerRefs
in interfaceNamedBean
- Returns:
- ArrayList of the listeners
-
updateListenerRef
@OverridingMethodsMustInvokeSuper public void updateListenerRef(java.beans.PropertyChangeListener l, java.lang.String newName)
- Specified by:
updateListenerRef
in interfaceNamedBean
-
getListenerRef
public java.lang.String getListenerRef(java.beans.PropertyChangeListener l)
Description copied from interface:NamedBean
Get the textual reference for the specific listener- Specified by:
getListenerRef
in interfaceNamedBean
- Parameters:
l
- the listener of interest- Returns:
- the textual reference
-
getNumPropertyChangeListeners
public int getNumPropertyChangeListeners()
Get the number of current listeners.- Specified by:
getNumPropertyChangeListeners
in interfaceNamedBean
- Returns:
- -1 if the information is not available for some reason.
-
getPropertyChangeListeners
@Nonnull public java.beans.PropertyChangeListener[] getPropertyChangeListeners()
Get allPropertyChangeListener
s currently attached to this object.- Specified by:
getPropertyChangeListeners
in interfacePropertyChangeProvider
- Returns:
- An array of PropertyChangeListeners.
-
getPropertyChangeListeners
@Nonnull public java.beans.PropertyChangeListener[] getPropertyChangeListeners(java.lang.String propertyName)
Get allPropertyChangeListener
s currently listening to changes to the specified property.- Specified by:
getPropertyChangeListeners
in interfacePropertyChangeProvider
- Parameters:
propertyName
- the name of the property of interest- Returns:
- an array of PropertyChangeListeners
-
getSystemName
@Nonnull public final java.lang.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 interfaceNamedBean
- Returns:
- the system-specific name
-
toString
@Nonnull public final java.lang.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.
-
toStringSuffix
protected java.lang.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 java.lang.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 interfaceNamedBean
- Returns:
- null if not set
-
setUserName
@OverridingMethodsMustInvokeSuper public void setUserName(java.lang.String s) throws NamedBean.BadUserNameException
Set the user name, normalizing it if needed.- Specified by:
setUserName
in interfaceNamedBean
- Parameters:
s
- the new user name- Throws:
NamedBean.BadUserNameException
- if the user name can not be normalized
-
firePropertyChange
@OverridingMethodsMustInvokeSuper protected void firePropertyChange(java.lang.String p, java.lang.Object old, java.lang.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.
-
describeState
@Nonnull public java.lang.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 interfaceNamedBean
- Parameters:
state
- the state to describe- Returns:
- the state in localized form
-
setProperty
@OverridingMethodsMustInvokeSuper public void setProperty(@Nonnull java.lang.String key, java.lang.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.Prior to JMRI 4.3, the key was of Object type. It was constrained to String to make these more like normal Java Beans.
- Specified by:
setProperty
in interfaceNamedBean
- Parameters:
key
- the property to setvalue
- the value of the property
-
getProperty
@OverridingMethodsMustInvokeSuper public java.lang.Object getProperty(@Nonnull java.lang.String key)
Retrieve the value associated with a key. If no value has been set for that key, returns null.- Specified by:
getProperty
in interfaceNamedBean
- Parameters:
key
- the property to get- Returns:
- The value of the property or null.
-
getPropertyKeys
@OverridingMethodsMustInvokeSuper @Nonnull public java.util.Set<java.lang.String> getPropertyKeys()
Retrieve the complete current set of keys.- Specified by:
getPropertyKeys
in interfaceNamedBean
- Returns:
- empty set if none
-
removeProperty
@OverridingMethodsMustInvokeSuper public void removeProperty(java.lang.String key)
Remove the key/value pair against the NamedBean.- Specified by:
removeProperty
in interfaceNamedBean
- Parameters:
key
- the property to remove
-
vetoableChange
public void vetoableChange(java.beans.PropertyChangeEvent evt) throws java.beans.PropertyVetoException
- Specified by:
vetoableChange
in interfaceNamedBean
- Throws:
java.beans.PropertyVetoException
-
equals
public boolean equals(java.lang.Object obj)
This implementation tests that
NamedBean.getSystemName()
is equal for this and obj.- Overrides:
equals
in classjava.lang.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 classjava.lang.Object
- Returns:
- hash code value is based on the system name.
-
compareSystemNameSuffix
@CheckReturnValue public int compareSystemNameSuffix(@Nonnull java.lang.String suffix1, @Nonnull java.lang.String suffix2, @Nonnull NamedBean n)
Compare the suffix of this NamedBean's name with the suffix of the argument NamedBean's name for theNamedBean.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 interfaceNamedBean
- Parameters:
suffix1
- The suffix for the 1st bean in the comparisonsuffix2
- The suffix for the 2nd bean in the comparisonn
- 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.
-
-