Package jmri.managers

Class AbstractManager<E extends NamedBean>

    • Method Detail

      • makeSystemName

        @Nonnull
public java.lang.String makeSystemName​(@Nonnull
                                       java.lang.String s,
                                       boolean logErrors,
                                       java.util.Locale locale)
        Create a SystemName by prepending the system name prefix to the name if not already present.

        The logErrors parameter is present to allow user interface input validation to use this method without logging system name validation errors as the user types.

        Note: implementations must call Manager.validateSystemNameFormat(java.lang.String, java.util.Locale) to ensure the returned name is valid.

        Specified by:
        makeSystemName in interface Manager<E extends NamedBean>
        Parameters:
        s - the item to make the system name for
        logErrors - true to log errors; false to not log errors
        locale - the locale for a localized exception; this is needed for the JMRI web server, which supports multiple locales
        Returns:
        a valid system name

      • getBySystemName

        @CheckForNull
public E getBySystemName​(@Nonnull
                         java.lang.String systemName)
        Locate an existing instance based on a system name.
        Specified by:
        getBySystemName in interface Manager<E extends NamedBean>
        Parameters:
        systemName - System Name of the required NamedBean
        Returns:
        requested NamedBean object or null if none exists

      • getBySystemName

        @CheckForNull
protected E getBySystemName​(java.lang.String systemName,
                            java.util.Comparator<java.lang.String> comparator)
        Protected method used by subclasses to over-ride the default behavior of getBySystemName when a simple string lookup is not sufficient.
        Parameters:
        systemName - the system name to check
        comparator - a Comparator encapsulating the system specific comparison behavior
        Returns:
        a named bean of the appropriate type, or null if not found

      • getByUserName

        @CheckForNull
public E getByUserName​(@Nonnull
                       java.lang.String userName)
        Locate an existing instance based on a user name.
        Specified by:
        getByUserName in interface Manager<E extends NamedBean>
        Parameters:
        userName - System Name of the required NamedBean
        Returns:
        requested NamedBean object or null if none exists

      • getNamedBean

        @CheckForNull
public E getNamedBean​(@Nonnull
                      java.lang.String name)
        Locate an existing instance based on a name.
        Specified by:
        getNamedBean in interface Manager<E extends NamedBean>
        Parameters:
        name - User Name or System Name of the required NamedBean
        Returns:
        requested NamedBean object or null if none exists

      • deleteBean

        @OverridingMethodsMustInvokeSuper
public void deleteBean​(@Nonnull
                       E bean,
                       @Nonnull
                       java.lang.String property)
                throws java.beans.PropertyVetoException
        Method for a UI to delete a bean.

        The UI should first request a "CanDelete", this will return a list of locations (and descriptions) where the bean is in use via throwing a VetoException, then if that comes back clear, or the user agrees with the actions, then a "DoDelete" can be called which inform the listeners to delete the bean, then it will be deregistered and disposed of.

        If a property name of "DoNotDelete" is thrown back in the VetoException then the delete process should be aborted.

        Specified by:
        deleteBean in interface Manager<E extends NamedBean>
        Parameters:
        bean - The NamedBean to be deleted
        property - The programmatic name of the request. "CanDelete" will enquire with all listeners if the item can be deleted. "DoDelete" tells the listener to delete the item
        Throws:
        java.beans.PropertyVetoException - If the recipients wishes the delete to be aborted (see above)

      • getOuterBean

        protected E getOuterBean​(E bean)
        Get the outer bean of an encapsulated bean. Some managers encapsulates the beans and those managers needs to override this method.
        Parameters:
        bean - the bean
        Returns:
        the most outer bean or the bean itself if there is no outer bean

      • propertyChange

        @OverridingMethodsMustInvokeSuper
public void propertyChange​(java.beans.PropertyChangeEvent e)
        The PropertyChangeListener interface in this class is intended to keep track of user name changes to individual NamedBeans. It is not completely implemented yet. In particular, listeners are not added to newly registered objects.
        Specified by:
        propertyChange in interface java.beans.PropertyChangeListener
        Parameters:
        e - the event

      • getNamedBeanSet

        @Nonnull
public java.util.SortedSet<E> getNamedBeanSet()
        Provide an unmodifiable SortedSet of NamedBeans in system-name order.

        Note: This is the fastest of the accessors, and is the only long-term form.

        Note: This is a live set; the contents are kept up to date

        Specified by:
        getNamedBeanSet in interface Manager<E extends NamedBean>
        Returns:
        Unmodifiable access to a SortedSet of NamedBeans

      • fireVetoableChange

        @OverridingMethodsMustInvokeSuper
public void fireVetoableChange​(java.lang.String p,
                               java.lang.Object old,
                               java.lang.Object n)
                        throws java.beans.PropertyVetoException
        Inform all registered listeners of a vetoable change. If the propertyName is "CanDelete" ALL listeners with an interest in the bean will throw an exception, which is recorded returned back to the invoking method, so that it can be presented back to the user. However if a listener decides that the bean can not be deleted then it should throw an exception with a property name of "DoNotDelete", this is thrown back up to the user and the delete process should be aborted.
        Specified by:
        fireVetoableChange in interface VetoableChangeFirer
        Overrides:
        fireVetoableChange in class VetoableChangeSupport
        Parameters:
        p - The programmatic name of the property that is to be changed. "CanDelete" will inquire with all listeners if the item can be deleted. "DoDelete" tells the listener to delete the item.
        old - The old value of the property.
        n - The new value of the property.
        Throws:
        java.beans.PropertyVetoException - if the recipients wishes the delete to be aborted.

      • vetoableChange

        @OverridingMethodsMustInvokeSuper
public void vetoableChange​(java.beans.PropertyChangeEvent evt)
                    throws java.beans.PropertyVetoException
        Specified by:
        vetoableChange in interface java.beans.VetoableChangeListener
        Throws:
        java.beans.PropertyVetoException

      • getSystemPrefix

        @Nonnull
public final java.lang.String getSystemPrefix()
        Provide access to the system prefix string. This was previously called the "System letter" The implementation in AbstractManager should be final, but is not for four managers that have arbitrary prefixes.
        Specified by:
        getSystemPrefix in interface Manager<E extends NamedBean>
        Returns:
        the system prefix

      • setDataListenerMute

        public void setDataListenerMute​(boolean m)
        Temporarily suppress DataListener notifications.

        This avoids O(N^2) behavior when doing bulk updates, i.e. when loading lots of Beans. Note that this is (1) optional, in the sense that the manager is not required to mute and (2) if present, its' temporary, in the sense that the manager must do a cumulative notification when done.

        Specified by:
        setDataListenerMute in interface Manager<E extends NamedBean>
        Parameters:
        m - true if notifications should be suppressed; false otherwise

      • updateAutoNumber

        public void updateAutoNumber​(java.lang.String systemName)

      • createSystemName

        public java.lang.String createSystemName​(@Nonnull
                                         java.lang.String curAddress,
                                         @Nonnull
                                         java.lang.String prefix)
                                  throws JmriException
        Create a System Name from hardware address and system letter prefix. AbstractManager performs no validation.
        Parameters:
        curAddress - hardware address, no system prefix or type letter.
        prefix - - just system prefix, not including Type Letter.
        Returns:
        full system name with system prefix, type letter and hardware address.
        Throws:
        JmriException - if unable to create a system name.

      • checkNumeric

        protected java.lang.String checkNumeric​(@Nonnull
                                        java.lang.String curAddress)
                                 throws JmriException
        checks for numeric-only system names.
        Parameters:
        curAddress - the System name ( excluding both prefix and type letter) to check.
        Returns:
        unchanged if is numeric string.
        Throws:
        JmriException - if not numeric.