Package jmri.managers

Class AbstractProxyManager<E extends NamedBean>

java.lang.Object

jmri.beans.PropertyChangeSupport

jmri.beans.VetoableChangeSupport

jmri.managers.AbstractProxyManager<E>

Type Parameters:

E - the supported type of NamedBean

All Implemented Interfaces:

PropertyChangeListener, EventListener, PropertyChangeFirer, PropertyChangeProvider, SilenceablePropertyChangeProvider, VetoableChangeFirer, VetoableChangeProvider, Manager<E>, Manager.ManagerDataListener<E>, ProxyManager<E>

Direct Known Subclasses:

AbstractProvidingProxyManager, ProxyAnalogIOManager, ProxyMeterManager

public abstract class AbstractProxyManager<E extends NamedBean>
extends VetoableChangeSupport
implements ProxyManager<E>, PropertyChangeListener, Manager.ManagerDataListener<E>

Implementation of a Manager that can serves as a proxy for multiple system-specific implementations.

Automatically includes an Internal system, which need not be separately added any more.

Encapsulates access to the "Primary" manager, used by default, which is the first one provided.

Internally, this is done by using an ordered list of all non-Internal managers, plus a separate reference to the internal manager and default manager.

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 Manager<E>	defaultManager
(package private) final List<Manager.ManagerDataListener<E>>	listeners
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
AbstractProxyManager()

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.
void	addManager(Manager<E> m)	Add a Manager to the collection of Managers.
void	addPropertyChangeListener(PropertyChangeListener l)	Add a PropertyChangeListener to the listener list.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener)	Add a PropertyChangeListener for a specific property.
void	addVetoableChangeListener(VetoableChangeListener l)	Add a VetoableChangeListener to the listener list.
void	addVetoableChangeListener(String propertyName, VetoableChangeListener listener)	Add a VetoableChangeListener for a specific property.
void	contentsChanged(Manager.ManagerDataEvent<E> e)	Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods.
protected Manager<E>	createSystemManager(SystemConnectionMemo memo)	Try to create a system manager.
String	createSystemName(String curAddress, String prefix)
(package private) String	createSystemName(String curAddress, String prefix, Class<?> beanType)	Shared method to create a systemName based on the address base, the prefix and manager class.
void	deleteBean(E s, 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.
E	getBySystemName(String systemName)	Locate an existing instance based on a system name.
E	getByUserName(String userName)	Locate an existing instance based on a user name.
Manager<E>	getDefaultManager()	Get the default manager or the internal manager if no default manager has been set.
List<Manager<E>>	getDisplayOrderManagerList()	Get a list of all managers, with the default as the first item and internal default as the last item.
String	getEntryToolTip()	Get the Default Manager ToolTip.
Manager<E>	getInternalManager()
List<NamedBeanPropertyDescriptor<?>>	getKnownBeanProperties()	Return the descriptors for the system-specific properties of the NamedBeans that are kept in this manager.
protected Manager<E>	getManager(String systemName)	Get the manager for the given system name.
List<Manager<E>>	getManagerList()	Returns a list of all managers, including the internal manager.
protected Manager<E>	getManagerOrDefault(String systemName)	Get the manager for the given system name or the default manager if there is no matching manager.
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.
String	getNextValidSystemName(NamedBean currentBean)
int	getObjectCount()	Get the count of managed objects.
String	getSystemPrefix()	Provide access to the system prefix string.
protected Manager<E>	initInternal()
void	intervalAdded(Manager.ManagerDataEvent<E> e)	Sent after the indices in the index0,index1 interval have been inserted in the data model.
void	intervalRemoved(Manager.ManagerDataEvent<E> e)	Sent after the indices in the index0,index1 interval have been removed from the data model.
protected abstract Manager<E>	makeInternalManager()	Create specific internal manager as needed for concrete type.
String	makeSystemName(String s)	Create a SystemName by prepending the system name prefix to the name if not already present.
void	propertyChange(PropertyChangeEvent event)
protected void	recomputeNamedBeanSet()
void	register(E s)	Remember a NamedBean Object created outside the manager.
void	removeDataListener(Manager.ManagerDataListener<E> e)	Unregister a previously-added Manager.ManagerDataListener.
void	removePropertyChangeListener(PropertyChangeListener l)	Remove the specified listener from this object.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener)	Remove the specified listener of the specified property from this object.
void	removeVetoableChangeListener(VetoableChangeListener l)	Remove the specified listener from this object.
void	removeVetoableChangeListener(String propertyName, VetoableChangeListener listener)	Remove the specified listener of the specified property from this object.
void	setDataListenerMute(boolean m)	Temporarily suppress DataListener notifications.
void	setPropertyChangesSilenced(String propertyName, boolean silenced)	Suppress sending PropertyChangeEvents for the named property.
char	typeLetter()
String	validateSystemNameFormat(String systemName, Locale locale)	Validate the format of name, returning it unchanged if valid.
Manager.NameValidity	validSystemNameFormat(String systemName)	Validate system name format.

Methods inherited from class jmri.beans.VetoableChangeSupport

fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getVetoableChangeListeners, getVetoableChangeListeners

Methods inherited from class jmri.beans.PropertyChangeSupport

fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeListeners, getPropertyChangeListeners

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, getNamedBeanClass, getSubSystemNamePrefix, getSystemNamePrefix, getXMLOrder, isValidSystemNameFormat, makeSystemName, makeSystemName, validateBadCharsInSystemNameFormat, validateIntegerSystemNameFormat, validateNmraAccessorySystemNameFormat, validateSystemNameFormat, validateSystemNameFormatOnlyNumeric, validateSystemNamePrefix, validateTrimmedMin1NumberSystemNameFormat, validateTrimmedSystemNameFormat, validateUppercaseTrimmedSystemNameFormat

Methods inherited from interface jmri.beans.PropertyChangeProvider

getPropertyChangeListeners, getPropertyChangeListeners

Methods inherited from interface jmri.beans.VetoableChangeProvider

getVetoableChangeListeners, getVetoableChangeListeners

Field Details

silencedProperties

protected final Map<String,Boolean> silencedProperties

silenceableProperties

protected final Set<String> silenceableProperties

defaultManager

protected Manager<E extends NamedBean> defaultManager

listeners

final List<Manager.ManagerDataListener<E extends NamedBean>> listeners

Constructor Details

AbstractProxyManager

public AbstractProxyManager()

Method Details

getManagerList

public List<Manager<E>> getManagerList()

Returns a list of all managers, including the internal manager. This is not a live list, but it is in alpha order (don't assume default is at front)

Specified by:

getManagerList in interface ProxyManager<E extends NamedBean>

Returns:

the list of managers

getDisplayOrderManagerList

public List<Manager<E>> getDisplayOrderManagerList()

Get a list of all managers, with the default as the first item and internal default as the last item.

Specified by:

getDisplayOrderManagerList in interface ProxyManager<E extends NamedBean>

Returns:

the list of managers

getInternalManager

public Manager<E> getInternalManager()

getDefaultManager

@Nonnull
public Manager<E> getDefaultManager()

Get the default manager or the internal manager if no default manager has been set.

Specified by:

getDefaultManager in interface ProxyManager<E extends NamedBean>

Returns:

the default manager or the internal manager

addManager

public void addManager(@Nonnull
 Manager<E> m)

Add a Manager to the collection of Managers.

Specified by:

addManager in interface ProxyManager<E extends NamedBean>

Parameters:

m - the Manager to add; if manager has already been added, it will not be added again

initInternal

protected Manager<E> initInternal()

makeInternalManager

protected abstract Manager<E> makeInternalManager()

Create specific internal manager as needed for concrete type.

Returns:

an internal manager

getNamedBean

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

getBySystemName

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

getByUserName

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

validateSystemNameFormat

@Nonnull
public String validateSystemNameFormat(@Nonnull
 String systemName,
 @Nonnull
 Locale locale)

Validate the format of name, returning it unchanged if valid.

Although further restrictions may be added by system-specific implementations, at a minimum, the implementation must consider a name that does not start with the System Name prefix for this manager to be invalid, and must consider a name that is the same as the System Name prefix to be invalid.

Overriding implementations may rely on Manager.validSystemNameFormat(java.lang.String), however they must provide an actionable message in the thrown exception if that method does not return Manager.NameValidity.VALID. When overriding implementations of this method rely on validSystemNameFormat(), implementations of that method must not throw an exception, log an error, or otherwise disrupt the user.

This implementation locates a specific Manager based on the system name and validates against that. If no matching Manager exists, the default Manager attempts to validate the system name.

Specified by:

validateSystemNameFormat in interface Manager<E extends NamedBean>

Parameters:

systemName - the system name to validate

locale - the locale for a localized exception; this is needed for the JMRI web server, which supports multiple locales

Returns:

the unchanged value of the name parameter

validSystemNameFormat

public Manager.NameValidity validSystemNameFormat(@Nonnull
 String systemName)

Validate system name format. Locate a system specific Manager based on a system name.

Specified by:

validSystemNameFormat in interface Manager<E extends NamedBean>

Parameters:

systemName - the system name

Returns:

if a manager is found, return its determination of validity of system name format. Return INVALID if no manager exists.

dispose

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>

getManager

@CheckForNull
protected Manager<E> getManager(@Nonnull
 String systemName)

Get the manager for the given system name.

Parameters:

systemName - the given name

Returns:

the requested manager or null if there is no matching manager

getManagerOrDefault

@Nonnull
protected Manager<E> getManagerOrDefault(@Nonnull
 String systemName)

Get the manager for the given system name or the default manager if there is no matching manager.

Parameters:

systemName - the given name

Returns:

the requested manager or the default manager if there is no matching manager

createSystemName

String createSystemName(String curAddress,
 String prefix,
 Class<?> beanType)
                 throws JmriException

Shared method to create a systemName based on the address base, the prefix and manager class.

Parameters:

curAddress - base address to use

prefix - system prefix to use

beanType - Bean Type for manager (method is used for Turnout and Sensor Managers)

Returns:

a valid system name for this connection

Throws:

JmriException - if systemName cannot be created

createSystemName

@Nonnull
public String createSystemName(@Nonnull
 String curAddress,
 @Nonnull
 String prefix)
                        throws JmriException

Throws:

JmriException

getNextValidSystemName

@Nonnull
public String getNextValidSystemName(@Nonnull
 NamedBean currentBean)
                              throws JmriException

Throws:

JmriException

deleteBean

public void deleteBean(@Nonnull
 E s,
 @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:

s - 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)

createSystemManager

protected Manager<E> createSystemManager(@Nonnull
 SystemConnectionMemo memo)

Try to create a system manager. If this proxy manager is able to create a system manager, the concrete class must implement this method.

Parameters:

memo - the system connection memo for this connection

Returns:

the new manager or null if it's not possible to create the manager

getEntryToolTip

public String getEntryToolTip()

Get the Default Manager ToolTip. Get a manager-specific tool tip for adding an entry to the manager.

Specified by:

getEntryToolTip in interface Manager<E extends NamedBean>

Returns:

the tool tip or null to disable the tool tip

register

public void register(@Nonnull
 E s)

Remember a NamedBean Object created outside the manager.

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

Forwards the register request to the matching system.

Specified by:

register in interface Manager<E extends NamedBean>

Parameters:

s - the bean

deregister

public void deregister(@Nonnull
 E s)

Forget a NamedBean Object created outside the manager.

The non-system-specific RouteManager uses this method.

Forwards the deregister request to the matching system.

Specified by:

deregister in interface Manager<E extends NamedBean>

Parameters:

s - the name

getKnownBeanProperties

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

Return the descriptors for the system-specific properties of the NamedBeans that are kept in this manager. List does not contain duplicates.

Specified by:

getKnownBeanProperties in interface Manager<E extends NamedBean>

Returns:

list of known properties, or empty list if there are none

addPropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void addPropertyChangeListener(PropertyChangeListener l)

Add a PropertyChangeListener to the listener list.

Specified by:

addPropertyChangeListener in interface PropertyChangeProvider

Overrides:

addPropertyChangeListener in class PropertyChangeSupport

Parameters:

l - The PropertyChangeListener to be added

removePropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void removePropertyChangeListener(PropertyChangeListener l)

Remove the specified listener from this object.

Specified by:

removePropertyChangeListener in interface PropertyChangeProvider

Overrides:

removePropertyChangeListener in class PropertyChangeSupport

Parameters:

l - The PropertyChangeListener to remove.

addPropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void addPropertyChangeListener(String propertyName,
 PropertyChangeListener listener)

Add a PropertyChangeListener for a specific property.

Specified by:

addPropertyChangeListener in interface PropertyChangeProvider

Overrides:

addPropertyChangeListener in class PropertyChangeSupport

Parameters:

propertyName - The name of the property to listen on.

listener - The PropertyChangeListener to be added

removePropertyChangeListener

@OverridingMethodsMustInvokeSuper
public void removePropertyChangeListener(String propertyName,
 PropertyChangeListener listener)

Remove the specified listener of the specified property from this object.

Specified by:

removePropertyChangeListener in interface PropertyChangeProvider

Overrides:

removePropertyChangeListener in class PropertyChangeSupport

Parameters:

propertyName - The name of the property to stop listening to.

listener - The PropertyChangeListener to remove.

addVetoableChangeListener

@OverridingMethodsMustInvokeSuper
public void addVetoableChangeListener(VetoableChangeListener l)

Add a VetoableChangeListener to the listener list.

Specified by:

addVetoableChangeListener in interface VetoableChangeProvider

Overrides:

addVetoableChangeListener in class VetoableChangeSupport

Parameters:

l - The VetoableChangeListener to be added

removeVetoableChangeListener

@OverridingMethodsMustInvokeSuper
public void removeVetoableChangeListener(VetoableChangeListener l)

Remove the specified listener from this object.

Specified by:

removeVetoableChangeListener in interface VetoableChangeProvider

Overrides:

removeVetoableChangeListener in class VetoableChangeSupport

Parameters:

l - The VetoableChangeListener to remove.

addVetoableChangeListener

@OverridingMethodsMustInvokeSuper
public void addVetoableChangeListener(String propertyName,
 VetoableChangeListener listener)

Add a VetoableChangeListener for a specific property.

Specified by:

addVetoableChangeListener in interface VetoableChangeProvider

Overrides:

addVetoableChangeListener in class VetoableChangeSupport

Parameters:

propertyName - The name of the property to listen on.

listener - The VetoableChangeListener to be added

removeVetoableChangeListener

@OverridingMethodsMustInvokeSuper
public void removeVetoableChangeListener(String propertyName,
 VetoableChangeListener listener)

Remove the specified listener of the specified property from this object.

Specified by:

removeVetoableChangeListener in interface VetoableChangeProvider

Overrides:

removeVetoableChangeListener in class VetoableChangeSupport

Parameters:

propertyName - The name of the property to stop listening to.

listener - The VetoableChangeListener to remove.

propertyChange

public void propertyChange(PropertyChangeEvent event)

Specified by:

propertyChange in interface PropertyChangeListener

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 memo for the manager returned by getDefaultManager(), or the Internal system connection memo if there is no default manager

getSystemPrefix

@Nonnull
public String getSystemPrefix()

Description copied from interface: Manager

Provide access to the system prefix string. This was previously called the "System letter"

Specified by:

getSystemPrefix in interface Manager<E extends NamedBean>

Returns:

The system-specific prefix letter for the primary implementation

typeLetter

public char typeLetter()

Specified by:

typeLetter in interface Manager<E extends NamedBean>

Returns:

The type letter for for the primary implementation

makeSystemName

@Nonnull
public String makeSystemName(@Nonnull
 String s)

Create a SystemName by prepending the system name prefix to the name if not already present.

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

Returns:

A system name from a user input, typically a number.

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

recomputeNamedBeanSet

protected void recomputeNamedBeanSet()

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

setPropertyChangesSilenced

@OverridingMethodsMustInvokeSuper
public void setPropertyChangesSilenced(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)

contentsChanged

public void contentsChanged(Manager.ManagerDataEvent<E> e)

Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods. From Manager.ManagerDataListener, receives notifications from underlying managers.

Specified by:

contentsChanged in interface Manager.ManagerDataListener<E extends NamedBean>

Parameters:

e - encapsulates event information

intervalAdded

public void intervalAdded(Manager.ManagerDataEvent<E> e)

Sent after the indices in the index0,index1 interval have been inserted in the data model. From Manager.ManagerDataListener, receives notifications from underlying managers.

Specified by:

intervalAdded in interface Manager.ManagerDataListener<E extends NamedBean>

Parameters:

e - encapsulates the event information

intervalRemoved

public void intervalRemoved(Manager.ManagerDataEvent<E> e)

Sent after the indices in the index0,index1 interval have been removed from the data model. From Manager.ManagerDataListener, receives notifications from underlying managers.

Specified by:

intervalRemoved in interface Manager.ManagerDataListener<E extends NamedBean>

Parameters:

e - encapsulates the event information

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