Package jmri

Interface NamedBean

All Superinterfaces:
Comparable<NamedBean>, PropertyChangeProvider
All Known Subinterfaces:
AddressedIdTag, AnalogActionBean, AnalogExpressionBean, AnalogIO, Audio, AudioBuffer, AudioListener, AudioSource, AverageMeter, CatalogTree, CollectingReporter, Conditional, ConditionalNG, CurrentMeter, DigitalActionBean, DigitalBooleanActionBean, DigitalExpressionBean, DigitalIO, GlobalVariable, IdTag, Light, Logix, LogixNG, MaleAnalogActionSocket, MaleAnalogExpressionSocket, MaleDigitalActionSocket, MaleDigitalBooleanActionSocket, MaleDigitalExpressionSocket, MaleStringActionSocket, MaleStringExpressionSocket, Memory, Meter, Module, NamedTable, RailCom, Reporter, Route, Section, Sensor, Signal, SignalGroup, SignalHead, SignalMast, SignalMastLogic, SignalSystem, StringActionBean, StringExpressionBean, StringIO, Timebase, Transit, Turnout, VariableControlSpanBean, VariableLight, VoltageMeter
All Known Implementing Classes:
AbstractAnalogAction, AbstractAnalogExpression, AbstractAnalogIO, AbstractAudio, AbstractAudioBuffer, AbstractAudioListener, AbstractAudioSource, AbstractBase, AbstractCatalogTree, AbstractDigitalAction, AbstractDigitalBooleanAction, AbstractDigitalExpression, AbstractIdTag, AbstractIdTagReporter, AbstractLight, AbstractMemory, AbstractNamedBean, AbstractNamedBeanDecorator, AbstractNamedTable, AbstractRailComReporter, AbstractReporter, AbstractSensor, AbstractSignalHead, AbstractSignalMast, AbstractStringAction, AbstractStringExpression, AbstractStringIO, AbstractTurnout, AbstractVariableLight, AcelaLight, AcelaSensor, AcelaSignalHead, AcelaTurnout, ActionAtomicBoolean, ActionAudio, ActionAudioIcon, ActionBlock, ActionClearSlots, ActionClock, ActionClockRate, ActionCreateBeansFromTable, ActionDispatcher, ActionEntryExit, ActionFindTableRowOrColumn, ActionLayoutTurnout, ActionLight, ActionLightIntensity, ActionListenOnBeans, ActionListenOnBeansLocalVariable, ActionListenOnBeansTable, ActionLocalVariable, ActionMemory, ActionOBlock, ActionPositionable, ActionPositionableByClass, ActionPower, ActionReporter, ActionRequestUpdateAllSensors, ActionRequestUpdateOfSensor, ActionRequestUpdateOfTurnout, ActionScript, ActionSensor, ActionSetReporter, ActionShutDownTask, ActionSignalHead, ActionSignalMast, ActionSound, ActionTable, ActionThrottle, ActionThrottleFunction, ActionTimer, ActionTurnout, ActionTurnoutLock, ActionUpdateSlots, ActionWarrant, AnalogActionLightIntensity, AnalogActionMemory, AnalogExpressionAnalogIO, AnalogExpressionConstant, AnalogExpressionLocalVariable, AnalogExpressionMemory, AnalogFormula, AnalogMany, And, Antecedent, AnymaDMX_UsbLight, BiDiBLight, BiDiBReporter, BiDiBSensor, BiDiBSignalMast, BiDiBTurnout, Block, Break, CatalogTreeFS, CatalogTreeIndex, CbusLight, CbusReporter, CbusSensor, CbusTurnout, ClipboardMany, ConnectionName, Continue, Dcc4PcReporter, Dcc4PcSensor, DCCppLight, DCCppSensor, DCCppTurnout, DccSignalHead, DccSignalMast, DebuggerMaleAnalogActionSocket, DebuggerMaleAnalogExpressionSocket, DebuggerMaleDigitalActionSocket, DebuggerMaleDigitalBooleanActionSocket, DebuggerMaleDigitalExpressionSocket, DebuggerMaleStringActionSocket, DebuggerMaleStringExpressionSocket, DefaultAverageMeter, DefaultClipboard, DefaultConditional, DefaultConditionalNG, DefaultCsvNamedTable, DefaultGlobalVariable, DefaultIdTag, DefaultInternalNamedTable, DefaultLogix, DefaultLogixNG, DefaultMaleAnalogActionSocket, DefaultMaleAnalogExpressionSocket, DefaultMaleDigitalActionSocket, DefaultMaleDigitalBooleanActionSocket, DefaultMaleDigitalExpressionSocket, DefaultMaleStringActionSocket, DefaultMaleStringExpressionSocket, DefaultMemory, DefaultMeter, DefaultMeter.DefaultCurrentMeter, DefaultMeter.DefaultVoltageMeter, DefaultModule, DefaultRailCom, DefaultRoute, DefaultSection, DefaultSignalAppearanceMap, DefaultSignalGroup, DefaultSignalHead, DefaultSignalMastLogic, DefaultSignalSystem, DefaultStringIO, DefaultTransit, DestinationPoints, DigitalBooleanLogixAction, DigitalBooleanMany, DigitalCallModule, DigitalCallModule, DigitalFormula, DigitalFormula, DigitalMany, DoAnalogAction, DoStringAction, DoubleTurnoutSignalHead, EasyDccTurnout, EcosReporter, EcosSensor, EcosTurnout, EliteXNetTurnout, EnableLogix, EnableLogixNG, Error, ExecuteAction, ExecuteDelayed, ExecuteProgram, Exit, ExpressionAudio, ExpressionBlock, ExpressionClock, ExpressionConditional, ExpressionDispatcher, ExpressionEntryExit, ExpressionLight, ExpressionLinuxLinePower, ExpressionLocalVariable, ExpressionMemory, ExpressionOBlock, ExpressionPower, ExpressionReference, ExpressionReporter, ExpressionScript, ExpressionSection, ExpressionSensor, ExpressionSensorEdge, ExpressionSignalHead, ExpressionSignalMast, ExpressionSlotUsage, ExpressionTransit, ExpressionTurnout, ExpressionWarrant, False, FileAsFlag, For, ForEach, ForEachWithDelay, Hold, IfThenElse, IpocsLight, IpocsSensor, IpocsTurnout, JavaSoundAudioBuffer, JavaSoundAudioListener, JavaSoundAudioSource, JMRIClientLight, JMRIClientReporter, JMRIClientSensor, JMRIClientTurnout, JoalAudioBuffer, JoalAudioListener, JoalAudioSource, JsonDecode, LastResultOfDigitalExpression, LayoutBlock, LNCPSignalMast, LnLight, LnReporter, LnSensor, LnThrottleStringIO, LnTurnout, LogData, LogData, Logix, LogLocalVariables, LsDecSignalHead, MarklinSensor, MarklinTurnout, MatrixSignalMast, MergSD2SignalHead, MqttLight, MqttReporter, MqttSensor, MqttSignalMast, MqttTurnout, MrcTurnout, Mx1Turnout, NceLight, NceSensor, NceTurnout, Not, NullAudioBuffer, NullAudioListener, NullAudioSource, NullBase, OBlock, OlcbLight, OlcbReporter, OlcbSensor, OlcbSignalMast, OlcbStringIO, OlcbTurnout, OperationsProStartAutomation, Or, ProgramOnMain, Publish, QuadOutputSignalHead, RaspberryPiSensor, RaspberryPiTurnout, Return, RfidReporter, RfidSensor, RpsReporter, RpsSensor, RunOnce, SCWarrant, SE8cSignalHead, SE8cSignalHead, SendMergCbusEvent, SensorGroupConditional, Sequence, SerialLight, SerialLight, SerialLight, SerialLight, SerialLight, SerialLight, SerialSensor, SerialSensor, SerialSensor, SerialSensor, SerialSensor, SerialSensor, SerialSignalHead, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialX10Light, SetLocalVariables, SetSpeedZero, ShowDialog, ShutdownComputer, SignalHeadSignalMast, SimpleTimebase, SimulateTurnoutFeedback, SingleTurnoutSignalHead, SpecificDmxLight, SpecificInsteonLight, SpecificInsteonLight, SpecificLight, SpecificLight, SpecificLight, SpecificX10Light, SpecificX10Light, SprogCSTurnout, SprogTurnout, SRCPSensor, SRCPTurnout, StringActionMemory, StringActionStringIO, StringExpressionConstant, StringExpressionMemory, StringExpressionStringIO, StringFormula, StringMany, Subscribe, TableForEach, TamsSensor, TamsTurnout, Timeout, TimeoutReporter, TimeoutRfidSensor, Timer, TimeSinceMidnight, TrackReporter, TranspondingTag, TriggerOnce, TriggerRoute, TripleOutputSignalHead, TripleTurnoutSignalHead, True, TurnoutSignalMast, VirtualSignalHead, VirtualSignalMast, Warrant, WebBrowser, WebRequest, WindowManagement, XBeeLight, XBeeSensor, XBeeTurnout, XNetLight, XNetSensor, XNetTurnout, XpaTurnout, Z21CanReporter, Z21CanSensor, Z21Reporter, Z21RMBusSensor, Z21XNetTurnout, ZTC611XNetTurnout
public interface NamedBean extends Comparable<NamedBean>, PropertyChangeProvider
Provides common services for classes representing objects on the layout, and allows a common form of access by their Managers.

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:

  • Field Details

  • Method Details

    • getUserName

      @CheckReturnValue @CheckForNull 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.
      Returns:
      null if not set

    • setUserName

      void setUserName(@CheckForNull String s) throws NamedBean.BadUserNameException
      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

      @CheckReturnValue @Nonnull String 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

      @Nonnull 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.

      Overrides:
      toString in class Object
      Returns:
      the system-specific name

    • getDisplayName

      @CheckReturnValue @Nonnull default String getDisplayName()
      Get user name if it exists, otherwise return System name.
      Returns:
      the user name or system-specific name

    • getDisplayName

      @CheckReturnValue @Nonnull default String getDisplayName(NamedBean.DisplayOptions options)
      Get the name to display, formatted per NamedBean.DisplayOptions.
      Parameters:
      options - the DisplayOptions to use
      Returns:
      the display name formatted per options

    • getRecommendedToolTip

      @CheckReturnValue @Nonnull default String getRecommendedToolTip()
      Get a recommended text for a tooltip when displaying the NamedBean, e.g. in a list or table. By default, this is the comment from the NamedBean, on the theory that the system name and/or user name are being displayed directly. Specific system implementations may override that.
      Returns:
      empty String if no recommendation.

    • 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 internally
      name - 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

      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 to
      listener - The listener. This may change in the future to be a subclass of NamedProprtyChangeListener that carries the name and listenerRef values internally
      name - 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

    • updateListenerRef

      void updateListenerRef(@Nonnull PropertyChangeListener l, String newName)

    • vetoableChange

      void vetoableChange(@Nonnull PropertyChangeEvent evt) throws PropertyVetoException
      Throws:
      PropertyVetoException

    • getListenerRef

      @CheckReturnValue String getListenerRef(@Nonnull PropertyChangeListener l)
      Get the textual reference for the specific listener
      Parameters:
      l - the listener of interest
      Returns:
      the textual reference

    • getListenerRefs

      @CheckReturnValue ArrayList<String> getListenerRefs()
      Returns a list of all the listeners references
      Returns:
      a list of textual references

    • getNumPropertyChangeListeners

      @CheckReturnValue int 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

      @InvokeOnLayoutThread void setState(int s) throws JmriException
      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

      @CheckReturnValue int 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

      @CheckReturnValue String describeState(int state)
      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

      @CheckReturnValue @CheckForNull String getComment()
      Get associated comment text.
      Returns:
      the comment or null

    • setComment

      void setComment(@CheckForNull String comment)
      Set associated comment text.

      Comments can be any valid text.

      Parameters:
      comment - the comment or null to remove an existing comment

    • getUsageReport

      default List<NamedBeanUsageReport> getUsageReport(@CheckForNull NamedBean bean)
      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

      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.

      Parameters:
      key - the property to set
      value - the value of the property

    • getProperty

      @CheckReturnValue @CheckForNull Object getProperty(@Nonnull String key)
      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

      void removeProperty(@Nonnull String key)
      Remove the key/value pair against the NamedBean.
      Parameters:
      key - the property to remove

    • getPropertyKeys

      @CheckReturnValue @Nonnull Set<String> getPropertyKeys()
      Retrieve the complete current set of keys.
      Returns:
      empty set if none

    • getBeanType

      @CheckReturnValue @Nonnull 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.
      Returns:
      a string of the bean type, eg Turnout, Sensor etc

    • normalizeUserName

      @CheckReturnValue @CheckForNull static String normalizeUserName(@CheckForNull String inputName) throws NamedBean.BadUserNameException
      Enforces, 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

      @CheckReturnValue default int compareTo(NamedBean n2)
      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 the compareSystemNameSuffix(java.lang.String, java.lang.String, jmri.NamedBean) method.
      Specified by:
      compareTo in interface Comparable<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 the compareTo(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 comparison
      suffix2 - The suffix for the 2nd bean in the comparison
      n2 - 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.