Class AbstractManager<E extends NamedBean>
- Type Parameters:
E
- the class this manager supports
- All Implemented Interfaces:
PropertyChangeListener
,VetoableChangeListener
,EventListener
,PropertyChangeFirer
,PropertyChangeProvider
,SilenceablePropertyChangeProvider
,VetoableChangeFirer
,VetoableChangeProvider
,Manager<E>
- Direct Known Subclasses:
AbstractAnalogIOManager
,AbstractAudioManager
,AbstractLightManager
,AbstractMemoryManager
,AbstractMeterManager
,AbstractReporterManager
,AbstractSensorManager
,AbstractSignalHeadManager
,AbstractStringIOManager
,AbstractTurnoutManager
,BlockManager
,DefaultCatalogTreeManager
,DefaultConditionalManager
,DefaultIdTagManager
,DefaultLogixManager
,DefaultRouteManager
,DefaultSignalGroupManager
,DefaultSignalMastLogicManager
,DefaultSignalMastManager
,DefaultSignalSystemManager
,DefaultVariableLightManager
,EcosLocoAddressManager
,LayoutBlockManager
,NamedBeanHandleManager
,OBlockManager
,SectionManager
,TransitManager
,WarrantManager
public abstract class AbstractManager<E extends NamedBean> extends VetoableChangeSupport implements Manager<E>, PropertyChangeListener, VetoableChangeListener
Note that this does not enforce any particular system naming convention at the present time. They're just names...
It does include, with AbstractNamedBean, the implementation of the normalized user name.
See source file for extensive implementation notes.
-
Nested Class Summary
Nested classes/interfaces inherited from interface jmri.Manager
Manager.ManagerDataEvent<E extends NamedBean>, Manager.ManagerDataListener<E extends NamedBean>, Manager.NameValidity
-
Field Summary
Fields Modifier and Type Field Description protected TreeSet<E>
_beans
protected Hashtable<String,E>
_tsys
protected Hashtable<String,E>
_tuser
(package private) AtomicInteger
lastAutoNamedBeanRef
protected SystemConnectionMemo
memo
(package private) DecimalFormat
paddedNumber
protected Set<String>
silenceableProperties
protected Map<String,Boolean>
silencedProperties
Fields inherited from interface jmri.Manager
ANALOGIOS, AUDIO, BLOCKBOSS, BLOCKS, CONDITIONALS, CTCDATA, deprecatedManagerLogger, ENTRYEXIT, IDTAGS, LAYOUTBLOCKS, LIGHTS, LOGIXNG_ANALOG_ACTIONS, LOGIXNG_ANALOG_EXPRESSIONS, LOGIXNG_CONDITIONALNGS, LOGIXNG_DIGITAL_ACTIONS, LOGIXNG_DIGITAL_BOOLEAN_ACTIONS, LOGIXNG_DIGITAL_EXPRESSIONS, LOGIXNG_STRING_ACTIONS, LOGIXNG_STRING_EXPRESSIONS, LOGIXNG_TABLES, LOGIXNGS, LOGIXS, MEMORIES, METERFRAMES, METERS, OBLOCKS, PANELFILES, REPORTERS, ROUTES, SECTIONS, SENSORGROUPS, SENSORS, SIGNALGROUPS, SIGNALHEADS, SIGNALMASTLOGICS, SIGNALMASTS, STRINGIOS, TIMEBASE, TRANSITS, TURNOUTS, WARRANTS
-
Constructor Summary
Constructors Constructor Description AbstractManager()
AbstractManager(SystemConnectionMemo memo)
-
Method Summary
Modifier and Type Method Description void
addDataListener(Manager.ManagerDataListener<E> e)
Deprecated.protected String
checkNumeric(String curAddress)
checks for numeric-only system names.String
createSystemName(String curAddress, String prefix)
Create a System Name from hardware address and system letter prefix.void
deleteBean(E bean, String property)
Method for a UI to delete a bean.void
deregister(E s)
Forget a NamedBean Object created outside the manager.void
dispose()
Free resources when no longer used.protected void
fireDataListenersAdded(int start, int end, E changedBean)
Deprecated.protected void
fireDataListenersRemoved(int start, int end, E changedBean)
Deprecated.void
fireVetoableChange(String p, Object old, Object n)
Inform all registered listeners of a vetoable change.String
getAutoSystemName()
E
getBySystemName(String systemName)
Locate an existing instance based on a system name.protected E
getBySystemName(String systemName, Comparator<String> comparator)
Protected method used by subclasses to over-ride the default behavior of getBySystemName when a simple string lookup is not sufficient.E
getByUserName(String userName)
Locate an existing instance based on a user name.protected String
getIncrement(String curAddress, int increment)
Increment a hardware address.protected String
getIncrementFromExistingNumber(String curAddress, int increment)
Increment a hardware address with an existing number.protected E
getInstanceBySystemName(String systemName)
Deprecated.since 4.15.6; usegetBySystemName(java.lang.String)
insteadprotected E
getInstanceByUserName(String userName)
Deprecated.since 4.15.6; usegetByUserName(java.lang.String)
insteadList<NamedBeanPropertyDescriptor<?>>
getKnownBeanProperties()
By default there are no custom properties.SystemConnectionMemo
getMemo()
Get the system connection for this manager.E
getNamedBean(String name)
Locate an existing instance based on a name.List<E>
getNamedBeanList()
Deprecated.SortedSet<E>
getNamedBeanSet()
Provide an unmodifiable SortedSet of NamedBeans in system-name order.String
getNextValidAddress(String curAddress, String prefix)
Deprecated.since 4.21.3; use #getNextValidAddress(String, String, boolean) instead.String
getNextValidAddress(String curAddress, String prefix, boolean ignoreInitialExisting)
Get the Next valid hardware address.int
getObjectCount()
Get the count of managed objects.List<String>
getSystemNameList()
Deprecated.String
getSystemPrefix()
Provide access to the system prefix string.protected void
handleUserNameUniqueness(E s)
Invoked byregisterUserName(NamedBean)
to ensure uniqueness of the NamedBean during registration.String
makeSystemName(String s, boolean logErrors, Locale locale)
Create a SystemName by prepending the system name prefix to the name if not already present.void
propertyChange(PropertyChangeEvent e)
The PropertyChangeListener interface in this class is intended to keep track of user name changes to individual NamedBeans.void
register(E s)
Remember a NamedBean Object created outside the manager.protected void
registerSelf()
By default, register this manager to store as configuration information.protected void
registerUserName(E s)
Invoked byregister(NamedBean)
to register the user name of the bean.void
removeDataListener(Manager.ManagerDataListener<E> e)
Deprecated.void
setDataListenerMute(boolean m)
Deprecated.void
setPropertyChangesSilenced(String propertyName, boolean silenced)
Suppress sendingPropertyChangeEvent
s for the named property.void
updateAutoNumber(String systemName)
Manager.NameValidity
validSystemNameFormat(String systemName)
Test if parameter is a properly formatted system name.void
vetoableChange(PropertyChangeEvent evt)
Methods inherited from class jmri.beans.VetoableChangeSupport
addVetoableChangeListener, addVetoableChangeListener, fireVetoableChange, fireVetoableChange, fireVetoableChange, getVetoableChangeListeners, getVetoableChangeListeners, removeVetoableChangeListener, removeVetoableChangeListener
Methods inherited from class jmri.beans.PropertyChangeSupport
addPropertyChangeListener, addPropertyChangeListener, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface jmri.Manager
getBeanBySystemName, getBeanByUserName, getBeanTypeHandled, getBeanTypeHandled, getEntryToolTip, getNamedBeanClass, getSubSystemNamePrefix, getSystemNamePrefix, getXMLOrder, isValidSystemNameFormat, makeSystemName, makeSystemName, setPropertyChangesMuted, typeLetter, validateBadCharsInSystemNameFormat, validateIntegerSystemNameFormat, validateNmraAccessorySystemNameFormat, validateSystemNameFormat, validateSystemNameFormat, validateSystemNameFormatOnlyNumeric, validateSystemNamePrefix, validateTrimmedMin1NumberSystemNameFormat, validateTrimmedSystemNameFormat, validateUppercaseTrimmedSystemNameFormat
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
Methods inherited from interface jmri.beans.VetoableChangeProvider
addVetoableChangeListener, addVetoableChangeListener, getVetoableChangeListeners, getVetoableChangeListeners, removeVetoableChangeListener, removeVetoableChangeListener
-
Field Details
-
Constructor Details
-
Method Details
-
registerSelf
By default, register this manager to store as configuration information. Override to change that. -
getMemo
Get the system connection for this manager. -
makeSystemName
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 interfaceManager<E extends NamedBean>
- Parameters:
s
- the item to make the system name forlogErrors
- true to log errors; false to not log errorslocale
- the locale for a localized exception; this is needed for the JMRI web server, which supports multiple locales- Returns:
- a valid system name
-
dispose
Free resources when no longer used. Specifically, remove all references to and from this object, so it can be garbage-collected. -
getInstanceBySystemName
Deprecated.since 4.15.6; usegetBySystemName(java.lang.String)
insteadGet a NamedBean by its system name.- Parameters:
systemName
- the system name- Returns:
- the result of
getBySystemName(java.lang.String)
with systemName
-
getInstanceByUserName
Deprecated.since 4.15.6; usegetByUserName(java.lang.String)
insteadGet a NamedBean by its user name.- Parameters:
userName
- the user name- Returns:
- the result of
getByUserName(java.lang.String)
call, with userName
-
getBySystemName
Locate an existing instance based on a system name.- Specified by:
getBySystemName
in interfaceManager<E extends NamedBean>
- Parameters:
systemName
- System Name of the required NamedBean- Returns:
- requested NamedBean object or null if none exists
-
getBySystemName
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 checkcomparator
- a Comparator encapsulating the system specific comparison behavior- Returns:
- a named bean of the appropriate type, or null if not found
-
getByUserName
Locate an existing instance based on a user name.- Specified by:
getByUserName
in interfaceManager<E extends NamedBean>
- Parameters:
userName
- System Name of the required NamedBean- Returns:
- requested NamedBean object or null if none exists
-
getNamedBean
Locate an existing instance based on a name.- Specified by:
getNamedBean
in interfaceManager<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 String property) throws PropertyVetoExceptionMethod 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 interfaceManager<E extends NamedBean>
- Parameters:
bean
- The NamedBean to be deletedproperty
- 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:
PropertyVetoException
- If the recipients wishes the delete to be aborted (see above)
-
register
Remember a NamedBean Object created outside the manager.The non-system-specific SignalHeadManagers use this method extensively.
-
registerUserName
Invoked byregister(NamedBean)
to register the user name of the bean.- Parameters:
s
- the bean to register
-
handleUserNameUniqueness
Invoked byregisterUserName(NamedBean)
to ensure uniqueness of the NamedBean during registration.- Parameters:
s
- the bean to register
-
deregister
Forget a NamedBean Object created outside the manager.The non-system-specific RouteManager uses this method.
- Specified by:
deregister
in interfaceManager<E extends NamedBean>
- Parameters:
s
- the bean
-
getKnownBeanProperties
By default there are no custom properties.- Specified by:
getKnownBeanProperties
in interfaceManager<E extends NamedBean>
- Returns:
- empty list
-
propertyChange
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 interfacePropertyChangeListener
- Parameters:
e
- the event
-
getObjectCount
Get the count of managed objects.- Specified by:
getObjectCount
in interfaceManager<E extends NamedBean>
- Returns:
- the number of managed objects
-
getSystemNameList
Deprecated.Provide an unmodifiable List of system names.Note: this is ordered by the underlying NamedBeans, not on the Strings themselves.
Note: Access via
Manager.getNamedBeanSet()
is faster.Note: This is not a live list; the contents don't stay up to date
- Specified by:
getSystemNameList
in interfaceManager<E extends NamedBean>
- Returns:
- Unmodifiable access to a list of system names
-
getNamedBeanList
Deprecated.Provide an unmodifiable List of NamedBeans in system-name order.Note: Access via
Manager.getNamedBeanSet()
is faster.Note: This is not a live list; the contents don't stay up to date
- Specified by:
getNamedBeanList
in interfaceManager<E extends NamedBean>
- Returns:
- Unmodifiable access to a List of NamedBeans
-
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 interfaceManager<E extends NamedBean>
- Returns:
- Unmodifiable access to a SortedSet of NamedBeans
-
fireVetoableChange
@OverridingMethodsMustInvokeSuper public void fireVetoableChange(String p, Object old, Object n) throws PropertyVetoExceptionInform 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 interfaceVetoableChangeFirer
- Overrides:
fireVetoableChange
in classVetoableChangeSupport
- 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:
PropertyVetoException
- if the recipients wishes the delete to be aborted.
-
vetoableChange
@OverridingMethodsMustInvokeSuper public void vetoableChange(PropertyChangeEvent evt) throws PropertyVetoException- Specified by:
vetoableChange
in interfaceVetoableChangeListener
- Throws:
PropertyVetoException
-
validSystemNameFormat
Test if parameter is a properly formatted system name. Implementations of this method must not throw an exception, log an error, or otherwise disrupt the user.- Specified by:
validSystemNameFormat
in interfaceManager<E extends NamedBean>
- Parameters:
systemName
- the system name- Returns:
Manager.NameValidity.INVALID
if system name does not start withManager.getSystemNamePrefix()
;Manager.NameValidity.VALID_AS_PREFIX_ONLY
if system name equalsManager.getSystemNamePrefix()
; otherwiseManager.NameValidity.VALID
to allow Managers that do not perform more specific validation to be considered valid.
-
getSystemPrefix
Provide access to the system prefix string. This was previously called the "System letter" The implementation inAbstractManager
should be final, but is not for four managers that have arbitrary prefixes.- Specified by:
getSystemPrefix
in interfaceManager<E extends NamedBean>
- Returns:
- the system prefix
-
setPropertyChangesSilenced
@OverridingMethodsMustInvokeSuper public void setPropertyChangesSilenced(@Nonnull String propertyName, boolean silenced)Suppress sendingPropertyChangeEvent
s for the named property.Stopping the suppression of sending change events may send a PropertyChangeEvent if the property changed while silenced, but otherwise should not fire a PropertyChangeEvent.
- Specified by:
setPropertyChangesSilenced
in interfaceSilenceablePropertyChangeProvider
- Parameters:
propertyName
- the name of the property to mutesilenced
- true if events are to be suppressed; false otherwise
-
addDataListener
Deprecated.Register aManager.ManagerDataListener
to hear about adding or removing items from the list of NamedBeans.- Specified by:
addDataListener
in interfaceManager<E extends NamedBean>
- Parameters:
e
- the data listener to add
-
removeDataListener
Deprecated.Unregister a previously-addedManager.ManagerDataListener
.- Specified by:
removeDataListener
in interfaceManager<E extends NamedBean>
- Parameters:
e
- the data listener to remove- See Also:
Manager.addDataListener(ManagerDataListener)
-
setDataListenerMute
Deprecated.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 interfaceManager<E extends NamedBean>
- Parameters:
m
- true if notifications should be suppressed; false otherwise
-
fireDataListenersAdded
Deprecated. -
fireDataListenersRemoved
Deprecated. -
updateAutoNumber
-
getAutoSystemName
-
createSystemName
public String createSystemName(@Nonnull String curAddress, @Nonnull String prefix) throws JmriExceptionCreate 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
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.
-
getNextValidAddress
@Nonnull @Deprecated public final String getNextValidAddress(@Nonnull String curAddress, @Nonnull String prefix) throws JmriExceptionDeprecated.since 4.21.3; use #getNextValidAddress(String, String, boolean) instead.Get the Next valid hardware address. Used by the Turnout / Sensor / Reporter / Light Manager classes.- Parameters:
curAddress
- the starting hardware address to get the next valid from.prefix
- system prefix, just system name, not type letter.- Returns:
- the next valid system name, excluding both system name prefix and type letter.
- Throws:
JmriException
- if unable to get the current / next address, or more than 10 next addresses in use.
-
getNextValidAddress
@Nonnull public String getNextValidAddress(@Nonnull String curAddress, @Nonnull String prefix, boolean ignoreInitialExisting) throws JmriExceptionGet the Next valid hardware address. Used by the Turnout / Sensor / Reporter / Light Manager classes.System-specific methods may want to override getIncrement() rather than this one.
- Parameters:
curAddress
- the starting hardware address to get the next valid from.prefix
- system prefix, just system name, not type letter.ignoreInitialExisting
- false to return the starting address if it does not exist, else true to force an increment.- Returns:
- the next valid system name not already in use, excluding both system name prefix and type letter.
- Throws:
JmriException
- if unable to get the current / next address, or more than 10 next addresses in use.
-
getIncrement
Increment a hardware address.Default is to increment only an existing number. Sub-classes may wish to override this.
- Parameters:
curAddress
- the address to increment, excluding both system name prefix and type letter.increment
- the amount to increment by.- Returns:
- incremented address, no system prefix or type letter.
- Throws:
JmriException
- if unable to increment the address.
-
getIncrementFromExistingNumber
@Nonnull protected String getIncrementFromExistingNumber(String curAddress, int increment) throws JmriExceptionIncrement a hardware address with an existing number.- Parameters:
curAddress
- the address to increment, excluding both system name prefix and type letterincrement
- the amount to increment by.- Returns:
- incremented number.
- Throws:
JmriException
- if unable to increment the address.
-