Package jmri.managers

Class AbstractManager<E extends NamedBean>

java.lang.Object

jmri.beans.PropertyChangeSupport

jmri.beans.VetoableChangeSupport

jmri.managers.AbstractManager<E>

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, AbstractBaseManager, AbstractLightManager, AbstractMemoryManager, AbstractMeterManager, AbstractReporterManager, AbstractSensorManager, AbstractSignalHeadManager, AbstractStringIOManager, AbstractTurnoutManager, BlockManager, DefaultCatalogTreeManager, DefaultConditionalManager, DefaultConditionalNGManager, DefaultGlobalVariableManager, DefaultIdTagManager, DefaultLogixManager, DefaultLogixNGManager, DefaultModuleManager, DefaultNamedTableManager, DefaultRouteManager, DefaultSectionManager, DefaultSignalGroupManager, DefaultSignalMastLogicManager, DefaultSignalMastManager, DefaultSignalSystemManager, DefaultTransitManager, DefaultVariableLightManager, EcosLocoAddressManager, LayoutBlockManager, NamedBeanHandleManager, OBlockManager, WarrantManager

public abstract class AbstractManager<E extends NamedBean>
extends VetoableChangeSupport
implements Manager<E>, PropertyChangeListener, VetoableChangeListener

Abstract partial implementation for all Manager-type classes.

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.

See Also:

• NamedBean.normalizeUserName(java.lang.String)

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 final TreeSet<E>	_beans
protected final Hashtable<String,E>	_tsys
protected final Hashtable<String,E>	_tuser
(package private) AtomicInteger	lastAutoNamedBeanRef
protected final SystemConnectionMemo	memo
(package private) DecimalFormat	paddedNumber
protected final Set<String>	silenceableProperties
protected final Map<String,Boolean>	silencedProperties

Fields inherited from class jmri.beans.VetoableChangeSupport

vetoableChangeSupport

Fields inherited from class jmri.beans.PropertyChangeSupport

propertyChangeSupport

Fields inherited from interface jmri.Manager

ANALOGIOS, AUDIO, BLOCKBOSS, BLOCKS, CONDITIONALS, CTCDATA, ENTRYEXIT, IDTAGS, LAYOUTBLOCKS, LIGHTS, LOGIXNG_ANALOG_ACTIONS, LOGIXNG_ANALOG_EXPRESSIONS, LOGIXNG_CONDITIONALNGS, LOGIXNG_DIGITAL_ACTIONS, LOGIXNG_DIGITAL_BOOLEAN_ACTIONS, LOGIXNG_DIGITAL_EXPRESSIONS, LOGIXNG_GLOBAL_VARIABLES, LOGIXNG_MODULES, LOGIXNG_STRING_ACTIONS, LOGIXNG_STRING_EXPRESSIONS, LOGIXNG_TABLES, LOGIXNGS, LOGIXS, MEMORIES, METERFRAMES, METERS, OBLOCKS, PANELFILES, PROPERTY_BEANS, PROPERTY_CAN_DELETE, PROPERTY_DISPLAY_LIST_NAME, PROPERTY_DO_DELETE, PROPERTY_DO_NOT_DELETE, PROPERTY_LENGTH, 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)	Register a Manager.ManagerDataListener to hear about adding or removing items from the list of NamedBeans.
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)
protected void	fireDataListenersRemoved(int start, int end, E changedBean)
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.
List<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.
SortedSet<E>	getNamedBeanSet()	Provide an unmodifiable SortedSet of NamedBeans in system-name order.
int	getObjectCount()	Get the count of managed objects.
protected E	getOuterBean(E bean)	Get the outer bean of an encapsulated bean.
final String	getSystemPrefix()	Provide access to the system prefix string.
protected void	handleUserNameUniqueness(E s)	Invoked by registerUserName(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 by register(NamedBean) to register the user name of the bean.
void	removeDataListener(Manager.ManagerDataListener<E> e)	Unregister a previously-added Manager.ManagerDataListener.
void	setDataListenerMute(boolean m)	Temporarily suppress DataListener notifications.
void	setPropertyChangesSilenced(String propertyName, boolean silenced)	Suppress sending PropertyChangeEvents for the named property.
(package private) final void	setRegisterSelf()
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

getBeanTypeHandled, getBeanTypeHandled, getEntryToolTip, getNamedBeanClass, getSubSystemNamePrefix, getSystemNamePrefix, getXMLOrder, isValidSystemNameFormat, makeSystemName, makeSystemName, 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

memo

protected final SystemConnectionMemo memo

_beans

protected final TreeSet<E extends NamedBean> _beans

_tsys

protected final Hashtable<String,E extends NamedBean> _tsys

_tuser

protected final Hashtable<String,E extends NamedBean> _tuser

silencedProperties

protected final Map<String,Boolean> silencedProperties

silenceableProperties

protected final Set<String> silenceableProperties

lastAutoNamedBeanRef

AtomicInteger lastAutoNamedBeanRef

paddedNumber

DecimalFormat paddedNumber

Constructor Details

AbstractManager

public AbstractManager(SystemConnectionMemo memo)

AbstractManager

public AbstractManager()

Method Details

setRegisterSelf

final void setRegisterSelf()

registerSelf

@OverridingMethodsMustInvokeSuper
protected void registerSelf()

By default, register this manager to store as configuration information. Override to change that.

getMemo

@Nonnull
public SystemConnectionMemo getMemo()

Get the system connection for this manager.

Specified by:

getMemo in interface Manager<E extends NamedBean>

Returns:

the system connection for this manager

makeSystemName

@Nonnull
public String makeSystemName(@Nonnull
 String s,
 boolean logErrors,
 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

dispose

@OverridingMethodsMustInvokeSuper
public void dispose()

Free resources when no longer used. Specifically, remove all references to and from this object, so it can be garbage-collected.

Specified by:

dispose in interface Manager<E extends NamedBean>

getBySystemName

@CheckForNull
public E getBySystemName(@Nonnull
 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(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.

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
 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
 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
 String property)
                throws 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:

PropertyVetoException - If the recipients wishes the delete to be aborted (see above)

register

@OverridingMethodsMustInvokeSuper
public void register(@Nonnull
 E s)

Remember a NamedBean Object created outside the manager.

The non-system-specific SignalHeadManagers use this method extensively.

Specified by:

register in interface Manager<E extends NamedBean>

Parameters:

s - the bean

registerUserName

protected void registerUserName(E s)

Invoked by register(NamedBean) to register the user name of the bean.

Parameters:

s - the bean to register

handleUserNameUniqueness

protected void handleUserNameUniqueness(E s)

Invoked by registerUserName(NamedBean) to ensure uniqueness of the NamedBean during registration.

Parameters:

s - the bean to register

deregister

@OverridingMethodsMustInvokeSuper
public void deregister(@Nonnull
 E s)

Forget a NamedBean Object created outside the manager.

The non-system-specific RouteManager uses this method.

Specified by:

deregister in interface Manager<E extends NamedBean>

Parameters:

s - the bean

getKnownBeanProperties

@Nonnull
public List<NamedBeanPropertyDescriptor<?>> getKnownBeanProperties()

By default there are no custom properties.

Specified by:

getKnownBeanProperties in interface Manager<E extends NamedBean>

Returns:

empty list

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(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 PropertyChangeListener

Parameters:

e - the event

getObjectCount

@CheckReturnValue
public int getObjectCount()

Get the count of managed objects.

Specified by:

getObjectCount in interface Manager<E extends NamedBean>

Returns:

the number of managed objects

getNamedBeanSet

@Nonnull
public 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(String p,
 Object old,
 Object n)
                        throws 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:

PropertyVetoException - if the recipients wishes the delete to be aborted.

vetoableChange

@OverridingMethodsMustInvokeSuper
public void vetoableChange(PropertyChangeEvent evt)
                    throws PropertyVetoException

Specified by:

vetoableChange in interface VetoableChangeListener

Throws:

PropertyVetoException

validSystemNameFormat

public Manager.NameValidity validSystemNameFormat(@Nonnull
 String systemName)

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 interface Manager<E extends NamedBean>

Parameters:

systemName - the system name

Returns:

Manager.NameValidity.INVALID if system name does not start with Manager.getSystemNamePrefix(); Manager.NameValidity.VALID_AS_PREFIX_ONLY if system name equals Manager.getSystemNamePrefix(); otherwise Manager.NameValidity.VALID to allow Managers that do not perform more specific validation to be considered valid.

getSystemPrefix

@Nonnull
public final 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

setPropertyChangesSilenced

@OverridingMethodsMustInvokeSuper
public void setPropertyChangesSilenced(@Nonnull
 String propertyName,
 boolean silenced)

Suppress sending PropertyChangeEvents 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 interface SilenceablePropertyChangeProvider

Parameters:

propertyName - the name of the property to mute

silenced - true if events are to be suppressed; false otherwise

addDataListener

public void addDataListener(Manager.ManagerDataListener<E> e)

Register a Manager.ManagerDataListener to hear about adding or removing items from the list of NamedBeans.

Specified by:

addDataListener in interface Manager<E extends NamedBean>

Parameters:

e - the data listener to add

removeDataListener

public void removeDataListener(Manager.ManagerDataListener<E> e)

Unregister a previously-added Manager.ManagerDataListener.

Specified by:

removeDataListener in interface Manager<E extends NamedBean>

Parameters:

e - the data listener to remove

See Also:

• Manager.addDataListener(ManagerDataListener)

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

fireDataListenersAdded

protected void fireDataListenersAdded(int start,
 int end,
 E changedBean)

fireDataListenersRemoved

protected void fireDataListenersRemoved(int start,
 int end,
 E changedBean)

updateAutoNumber

public void updateAutoNumber(String systemName)

getAutoSystemName

public String getAutoSystemName()

createSystemName

public String createSystemName(@Nonnull
 String curAddress,
 @Nonnull
 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 String checkNumeric(@Nonnull
 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.