Interface NamedBean
- All Superinterfaces:
Comparable<NamedBean>
,PropertyChangeProvider
- All Known Subinterfaces:
AddressedIdTag
,AnalogIO
,Audio
,AudioBuffer
,AudioListener
,AudioSource
,CatalogTree
,CollectingReporter
,Conditional
,CurrentMeter
,DigitalIO
,IdTag
,Light
,Logix
,Memory
,Meter
,RailCom
,Reporter
,Route
,Sensor
,Signal
,SignalGroup
,SignalHead
,SignalMast
,SignalMastLogic
,SignalSystem
,StringIO
,Timebase
,Turnout
,VariableLight
,VoltageMeter
- All Known Implementing Classes:
AbstractAnalogIO
,AbstractAudio
,AbstractAudioBuffer
,AbstractAudioListener
,AbstractAudioSource
,AbstractCatalogTree
,AbstractIdTag
,AbstractIdTagReporter
,AbstractLight
,AbstractMemory
,AbstractNamedBean
,AbstractNamedBeanDecorator
,AbstractRailComReporter
,AbstractReporter
,AbstractSensor
,AbstractSignalHead
,AbstractSignalMast
,AbstractStringIO
,AbstractTurnout
,AbstractVariableLight
,AcelaLight
,AcelaSensor
,AcelaSignalHead
,AcelaTurnout
,AnymaDMX_UsbLight
,Block
,CatalogTreeFS
,CatalogTreeIndex
,CbusLight
,CbusReporter
,CbusSensor
,CbusTurnout
,Dcc4PcReporter
,Dcc4PcSensor
,DCCppLight
,DCCppSensor
,DCCppTurnout
,DccSignalHead
,DccSignalMast
,DefaultConditional
,DefaultIdTag
,DefaultLogix
,DefaultMemory
,DefaultMeter
,DefaultMeter.DefaultCurrentMeter
,DefaultMeter.DefaultVoltageMeter
,DefaultRailCom
,DefaultRoute
,DefaultSignalAppearanceMap
,DefaultSignalGroup
,DefaultSignalHead
,DefaultSignalMastLogic
,DefaultSignalSystem
,DestinationPoints
,DoubleTurnoutSignalHead
,EasyDccTurnout
,EcosReporter
,EcosSensor
,EcosTurnout
,EliteXNetTurnout
,IpocsLight
,IpocsSensor
,IpocsTurnout
,JavaSoundAudioBuffer
,JavaSoundAudioListener
,JavaSoundAudioSource
,JMRIClientLight
,JMRIClientReporter
,JMRIClientSensor
,JMRIClientTurnout
,JoalAudioBuffer
,JoalAudioListener
,JoalAudioSource
,LayoutBlock
,LNCPSignalMast
,LnLight
,LnReporter
,LnSensor
,LnTurnout
,LsDecSignalHead
,MarklinSensor
,MarklinTurnout
,MatrixSignalMast
,MergSD2SignalHead
,MqttLight
,MqttSensor
,MqttTurnout
,MrcTurnout
,Mx1Turnout
,NceLight
,NceSensor
,NceTurnout
,NullAudioBuffer
,NullAudioListener
,NullAudioSource
,OBlock
,OlcbLight
,OlcbSensor
,OlcbSignalMast
,OlcbTurnout
,QuadOutputSignalHead
,RaspberryPiSensor
,RaspberryPiTurnout
,RfidReporter
,RfidSensor
,RpsReporter
,RpsSensor
,SCWarrant
,SE8cSignalHead
,SE8cSignalHead
,Section
,SensorGroupConditional
,SerialLight
,SerialLight
,SerialLight
,SerialLight
,SerialLight
,SerialLight
,SerialSensor
,SerialSensor
,SerialSensor
,SerialSensor
,SerialSensor
,SerialSensor
,SerialSignalHead
,SerialTurnout
,SerialTurnout
,SerialTurnout
,SerialTurnout
,SerialTurnout
,SerialTurnout
,SerialTurnout
,SerialX10Light
,SignalHeadSignalMast
,SimpleTimebase
,SingleTurnoutSignalHead
,SpecificInsteonLight
,SpecificInsteonLight
,SpecificLight
,SpecificLight
,SpecificX10Light
,SpecificX10Light
,SprogCSTurnout
,SprogTurnout
,SRCPSensor
,SRCPTurnout
,TamsSensor
,TamsTurnout
,TimeoutReporter
,TimeoutRfidReporter
,TimeoutRfidSensor
,TrackReporter
,Transit
,TranspondingTag
,TripleOutputSignalHead
,TripleTurnoutSignalHead
,TurnoutSignalMast
,VirtualSignalHead
,VirtualSignalMast
,Warrant
,XBeeLight
,XBeeSensor
,XBeeTurnout
,XNetLight
,XNetSensor
,XNetTurnout
,XpaTurnout
,Z21CanReporter
,Z21CanSensor
,Z21Reporter
,Z21RMBusSensor
,Z21XNetTurnout
,ZTC611XNetTurnout
public interface NamedBean extends Comparable<NamedBean>, PropertyChangeProvider
Each object has two types of names:
The "system" name is provided by the system-specific implementations, and provides a unique mapping to the layout control system (for example LocoNet or NCE) and address within that system. It must be present and unique across the JMRI instance. Two beans are identical if they have the same system name; if not, not.
The "user" name is optional. It's free form text except for two restrictions:
- It can't be the empty string "". (A non-existant user name is coded as a null)
- And eventually, we may insist on normalizing user names to a specific
form, e.g. remove leading and trailing white space; see the
normalizeUserName(java.lang.String)
method
Each of these two names must be unique for every NamedBean of the same type on the layout and a single NamedBean cannot have a user name that is the same as the system name of another NamedBean of the same type. (The complex wording is saying that a single NamedBean object is allowed to have its system name and user name be the same, but that's the only non-uniqueness that's allowed within a specific type). Note that the uniqueness restrictions are currently not completely enforced, only warned about; a future version of JMRI will enforce this restriction.
For more information, see the Names and Naming page in the Technical Info pages.
This file is part of JMRI.
JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.
JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- See Also:
Manager
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
NamedBean.BadNameException
Parent class for a set of classes that describe if a user name or system name is a bad name.static class
NamedBean.BadSystemNameException
static class
NamedBean.BadUserNameException
static class
NamedBean.DisplayOptions
Display options forgetDisplayName(DisplayOptions)
.static class
NamedBean.DuplicateSystemNameException
-
Field Summary
Fields Modifier and Type Field Description static String
DISPLAY_NAME_FORMAT
Format used forgetDisplayName(DisplayOptions)
when displaying the user name and system name without quoation marks around the user name.static int
INCONSISTENT
Constant representing an "inconsistent" state, indicating that some inconsistency has been detected in the hardware readback.static String
PROPERTY_STATE
Property of changed state.static String
QUOTED_NAME_FORMAT
Format used forgetDisplayName(DisplayOptions)
when displaying the user name and system name with quoation marks around the user name.static int
UNKNOWN
Constant representing an "unknown" state, indicating that the object's state is not necessarily that of the actual layout hardware. -
Method Summary
Modifier and Type Method Description void
addPropertyChangeListener(PropertyChangeListener listener, String name, String listenerRef)
Request a call-back when a bound property changes.void
addPropertyChangeListener(String propertyName, PropertyChangeListener listener, String name, String listenerRef)
Request a call-back when a bound property changes.int
compareSystemNameSuffix(String suffix1, String suffix2, NamedBean n2)
Compare the suffix of this NamedBean's name with the suffix of the argument NamedBean's name for thecompareTo(jmri.NamedBean)
operation.default int
compareTo(NamedBean n2)
Provide a comparison between the system names of two beans.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.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.String
getComment()
Get associated comment text.default String
getDisplayName()
Get user name if it exists, otherwise return System name.default String
getDisplayName(NamedBean.DisplayOptions options)
Get the name to display, formatted perNamedBean.DisplayOptions
.default String
getFullyFormattedDisplayName()
Deprecated.since 4.17.2; usegetDisplayName(DisplayOptions)
withNamedBean.DisplayOptions.USERNAME_SYSTEMNAME
insteaddefault String
getFullyFormattedDisplayName(boolean userNameFirst)
Deprecated.since 4.17.2; usegetDisplayName(DisplayOptions)
withNamedBean.DisplayOptions.USERNAME_SYSTEMNAME
insteadString
getListenerRef(PropertyChangeListener l)
Get the textual reference for the specific listenerArrayList<String>
getListenerRefs()
Returns a list of all the listeners referencesint
getNumPropertyChangeListeners()
Number of current listeners.Object
getProperty(String key)
Retrieve the value associated with a key.PropertyChangeListener[]
getPropertyChangeListenersByReference(String name)
Get a list of all the property change listeners that are registered using a specific nameSet<String>
getPropertyKeys()
Retrieve the complete current set of keys.int
getState()
Provide generic access to internal state.String
getSystemName()
Get a system-specific name.default List<NamedBeanUsageReport>
getUsageReport(NamedBean bean)
Get a list of references for the specified bean.String
getUserName()
User's identification for the item.static String
normalizeUserName(String inputName)
Enforces, and as a user convenience converts to, the standard form for a user name.void
removeProperty(String key)
Remove the key/value pair against the NamedBean.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
setState(int s)
Provide generic access to internal state.void
setUserName(String s)
Set the user name, normalizing it if needed.String
toString()
Display the system-specific name.void
updateListenerRef(PropertyChangeListener l, String newName)
void
vetoableChange(PropertyChangeEvent evt)
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
Field Details
-
UNKNOWN
Constant representing an "unknown" state, indicating that the object's state is not necessarily that of the actual layout hardware. This is the initial state of a newly created object before communication with the layout.- See Also:
- Constant Field Values
-
INCONSISTENT
Constant representing an "inconsistent" state, indicating that some inconsistency has been detected in the hardware readback.- See Also:
- Constant Field Values
-
DISPLAY_NAME_FORMAT
Format used forgetDisplayName(DisplayOptions)
when displaying the user name and system name without quoation marks around the user name.- See Also:
- Constant Field Values
-
QUOTED_NAME_FORMAT
Format used forgetDisplayName(DisplayOptions)
when displaying the user name and system name with quoation marks around the user name.- See Also:
- Constant Field Values
-
PROPERTY_STATE
Property of changed state.- See Also:
- Constant Field Values
-
-
Method Details
-
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.- Returns:
- null if not set
-
setUserName
Set the user name, normalizing it if needed.- Parameters:
s
- the new user name- Throws:
NamedBean.BadUserNameException
- if the user name can not be normalized
-
getSystemName
Get a system-specific name. This encodes the hardware addressing information. Any given system name must be unique within the layout.- Returns:
- the system-specific name
-
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.
-
getDisplayName
Get user name if it exists, otherwise return System name.- Returns:
- the user name or system-specific name
-
getDisplayName
Get the name to display, formatted perNamedBean.DisplayOptions
.- Parameters:
options
- the DisplayOptions to use- Returns:
- the display name formatted per options
-
getFullyFormattedDisplayName
Deprecated.since 4.17.2; usegetDisplayName(DisplayOptions)
withNamedBean.DisplayOptions.USERNAME_SYSTEMNAME
insteadGet a fully formatted display that includes the SystemName and, if set, the UserName.This is the same as calling
getDisplayName(DisplayOptions)
with the parameterNamedBean.DisplayOptions.USERNAME_SYSTEMNAME
.- Returns:
UserName (SystemName)
orSystemName
if the UserName is null, empty, or matches the SystemName
-
getFullyFormattedDisplayName
@CheckReturnValue @Nonnull @Deprecated default String getFullyFormattedDisplayName(boolean userNameFirst)Deprecated.since 4.17.2; usegetDisplayName(DisplayOptions)
withNamedBean.DisplayOptions.USERNAME_SYSTEMNAME
insteadReturns a fully formatted display that includes the SystemName and UserName if set. This uses the format "%s (%s)"- Parameters:
userNameFirst
- ignored; retained for compatibility until removed- Returns:
UserName (SystemName)
orSystemName
if the UserName is null, empty, or matches the SystemName
-
addPropertyChangeListener
void addPropertyChangeListener(@Nonnull PropertyChangeListener listener, String name, String listenerRef)Request a call-back when a bound property changes. Bound properties are the known state, commanded state, user and system names.- Parameters:
listener
- The listener. This may change in the future to be a subclass of NamedProprtyChangeListener that carries the name and listenerRef values internallyname
- 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
void addPropertyChangeListener(@Nonnull String propertyName, @Nonnull PropertyChangeListener listener, String name, String listenerRef)Request a call-back when a bound property changes. Bound properties are the known state, commanded state, user and system names.- Parameters:
propertyName
- The name of the property to listen tolistener
- The listener. This may change in the future to be a subclass of NamedProprtyChangeListener that carries the name and listenerRef values internallyname
- 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
-
updateListenerRef
-
vetoableChange
- Throws:
PropertyVetoException
-
getListenerRef
Get the textual reference for the specific listener- Parameters:
l
- the listener of interest- Returns:
- the textual reference
-
getListenerRefs
Returns a list of all the listeners references- Returns:
- a list of textual references
-
getNumPropertyChangeListeners
Number of current listeners. May return -1 if the information is not available for some reason.- Returns:
- the number of listeners.
-
getPropertyChangeListenersByReference
@CheckReturnValue @Nonnull PropertyChangeListener[] getPropertyChangeListenersByReference(@Nonnull String name)Get a list of all the property change listeners that are registered using a specific name- Parameters:
name
- The name (either system or user) that the listener has registered as referencing this namedBean- Returns:
- empty list if none
-
dispose
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.
-
setState
Provide generic access to internal state.This generally shouldn't be used by Java code; use the class-specific form instead (e.g. setCommandedState in Turnout). This is provided to make scripts access easier to read.
- Parameters:
s
- the state- Throws:
JmriException
- general error when setting the state fails
-
getState
Provide generic access to internal state.This generally shouldn't be used by Java code; use the class-specific form instead (e.g. getCommandedState in Turnout). This is provided to make scripts easier to read.
- Returns:
- the state
-
describeState
Provide human-readable, localized version of state value.This method is intended for use when presenting to a human operator.
- Parameters:
state
- the state to describe- Returns:
- the state in localized form
-
getComment
Get associated comment text.- Returns:
- the comment or null
-
setComment
Set associated comment text.Comments can be any valid text.
- Parameters:
comment
- the comment or null to remove an existing comment
-
getUsageReport
Get a list of references for the specified bean.- Parameters:
bean
- The bean to be checked.- Returns:
- a list of NamedBeanUsageReports or an empty ArrayList.
-
setProperty
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.
- Parameters:
key
- the property to setvalue
- the value of the property
-
getProperty
Retrieve the value associated with a key. If no value has been set for that key, returns null.- Parameters:
key
- the property to get- Returns:
- The value of the property or null.
-
removeProperty
Remove the key/value pair against the NamedBean.- Parameters:
key
- the property to remove
-
getPropertyKeys
Retrieve the complete current set of keys.- Returns:
- empty set if none
-
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.- Returns:
- a string of the bean type, eg Turnout, Sensor etc
-
normalizeUserName
@CheckReturnValue @CheckForNull static String normalizeUserName(@CheckForNull String inputName) throws NamedBean.BadUserNameExceptionEnforces, and as a user convenience converts to, the standard form for a user name.This implementation just does a trim(), but later versions might e.g. do more extensive things.
- Parameters:
inputName
- User name to be normalized- Returns:
- A user name in standard normalized form or null if inputName was null
- Throws:
NamedBean.BadUserNameException
- If the inputName can't be converted to normalized form
-
compareTo
Provide a comparison between the system names of two beans. This provides a implementation for e.g.Comparator
. Returns 0 if the names are the same, -1 if the first argument orders before the second argument's name, +1 if the first argument's name orders after the second argument's name. The comparison is alphanumeric on the system prefix, then alphabetic on the type letter, then system-specific comparison on the two suffix parts via thecompareSystemNameSuffix(java.lang.String, java.lang.String, jmri.NamedBean)
method.- Specified by:
compareTo
in interfaceComparable<NamedBean>
- Parameters:
n2
- The second NamedBean in the comparison ("this" is the first one)- Returns:
- -1,0,+1 for ordering if the names are well-formed; may not provide proper ordering if the names are not well-formed.
-
compareSystemNameSuffix
@CheckReturnValue int compareSystemNameSuffix(@Nonnull String suffix1, @Nonnull String suffix2, @Nonnull NamedBean n2)Compare the suffix of this NamedBean's name with the suffix of the argument NamedBean's name for thecompareTo(jmri.NamedBean)
operation. This is intended to be a system-specific comparison that understands the various formats, etc.- Parameters:
suffix1
- The suffix for the 1st bean in the comparisonsuffix2
- The suffix for the 2nd bean in the comparisonn2
- 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.
-