Package jmri

Interface NamedBean

    • Method Detail

      • getUserName

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

      • getSystemName

        @CheckReturnValue
@Nonnull
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.
        Returns:
        the system-specific name

      • toString

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

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

      • getRecommendedToolTip

        @CheckReturnValue
@Nonnull
default java.lang.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
                               java.beans.PropertyChangeListener listener,
                               java.lang.String name,
                               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.
        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
                               java.lang.String propertyName,
                               @Nonnull
                               java.beans.PropertyChangeListener listener,
                               java.lang.String name,
                               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.
        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

      • vetoableChange

        void vetoableChange​(@Nonnull
                    java.beans.PropertyChangeEvent evt)
             throws java.beans.PropertyVetoException
        Throws:
        java.beans.PropertyVetoException

      • getListenerRef

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

      • getListenerRefs

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

      • getPropertyChangeListenersByReference

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

        Parameters:
        state - the state to describe
        Returns:
        the state in localized form

      • setComment

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

        Comments can be any valid text.

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

      • setProperty

        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.

        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
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.
        Parameters:
        key - the property to get
        Returns:
        The value of the property or null.

      • removeProperty

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

      • getBeanType

        @CheckReturnValue
@Nonnull
java.lang.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

      • 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 java.lang.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
                            java.lang.String suffix1,
                            @Nonnull
                            java.lang.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.