-
- Type Parameters:
E
- the type of NamedBean supported by this manager
- All Superinterfaces:
PropertyChangeProvider
,SilenceablePropertyChangeProvider
,VetoableChangeProvider
- All Known Subinterfaces:
AnalogActionManager
,AnalogExpressionManager
,AnalogIOManager
,AudioManager
,AudioSourceManager
,BaseManager<E>
,CatalogTreeManager
,ConditionalManager
,ConditionalNG_Manager
,DigitalActionManager
,DigitalBooleanActionManager
,DigitalExpressionManager
,GlobalVariableManager
,IdTagManager
,LightManager
,LogixManager
,LogixNG_Manager
,MemoryManager
,MeterManager
,ModuleManager
,NamedTableManager
,ProvidingManager<E>
,ProxyManager<B>
,RailComManager
,ReporterManager
,RouteManager
,SectionManager
,SensorManager
,SignalGroupManager
,SignalHeadManager
,SignalMastLogicManager
,SignalMastManager
,SignalSystemManager
,StringActionManager
,StringExpressionManager
,StringIOManager
,TransitManager
,TurnoutManager
,VariableLightManager
- All Known Implementing Classes:
AbstractAnalogIOManager
,AbstractAudioManager
,AbstractBaseManager
,AbstractLightManager
,AbstractManager
,AbstractMemoryManager
,AbstractMeterManager
,AbstractProvidingProxyManager
,AbstractProxyManager
,AbstractReporterManager
,AbstractSensorManager
,AbstractSignalHeadManager
,AbstractStringIOManager
,AbstractTurnoutManager
,AcelaLightManager
,AcelaSensorManager
,AcelaTurnoutManager
,BiDiBLightManager
,BiDiBReporterManager
,BiDiBSensorManager
,BiDiBTurnoutManager
,BlockManager
,CbusLightManager
,CbusReporterManager
,CbusSensorManager
,CbusTurnoutManager
,ConcentratorReporterManager
,ConcentratorSensorManager
,Dcc4PcReporterManager
,Dcc4PcSensorManager
,DCCppLightManager
,DCCppSensorManager
,DCCppTurnoutManager
,DefaultAnalogActionManager
,DefaultAnalogExpressionManager
,DefaultAudioManager
,DefaultAudioSourceManager
,DefaultCatalogTreeManager
,DefaultConditionalManager
,DefaultConditionalNGManager
,DefaultDigitalActionManager
,DefaultDigitalBooleanActionManager
,DefaultDigitalExpressionManager
,DefaultGlobalVariableManager
,DefaultIdTagManager
,DefaultLogixManager
,DefaultLogixNGManager
,DefaultMemoryManager
,DefaultModuleManager
,DefaultNamedTableManager
,DefaultRailComManager
,DefaultRouteManager
,DefaultSectionManager
,DefaultSignalGroupManager
,DefaultSignalMastLogicManager
,DefaultSignalMastManager
,DefaultSignalSystemManager
,DefaultStringActionManager
,DefaultStringExpressionManager
,DefaultTransitManager
,DefaultVariableLightManager
,EasyDccTurnoutManager
,EcosLocoAddressManager
,EcosReporterManager
,EcosSensorManager
,EcosTurnoutManager
,EliteXNetTurnoutManager
,EntryExitPairs
,InternalAnalogIOManager
,InternalLightManager
,InternalMeterManager
,InternalReporterManager
,InternalSensorManager
,InternalStringIOManager
,InternalTurnoutManager
,IpocsLightManager
,IpocsSensorManager
,IpocsTurnoutManager
,JMRIClientLightManager
,JMRIClientReporterManager
,JMRIClientSensorManager
,JMRIClientTurnoutManager
,LayoutBlockManager
,LnLightManager
,LnReporterManager
,LnSensorManager
,LnSensorManager
,LnStringIOManager
,LnTurnoutManager
,MarklinSensorManager
,MarklinTurnoutManager
,MqttLightManager
,MqttReporterManager
,MqttSensorManager
,MqttTurnoutManager
,MrcTurnoutManager
,Mx1TurnoutManager
,NamedBeanHandleManager
,NceLightManager
,NceSensorManager
,NceTurnoutManager
,OBlockManager
,OlcbLightManager
,OlcbReporterManager
,OlcbSensorManager
,OlcbTurnoutManager
,ProxyAnalogIOManager
,ProxyIdTagManager
,ProxyLightManager
,ProxyMeterManager
,ProxyReporterManager
,ProxySensorManager
,ProxyStringIOManager
,ProxyTurnoutManager
,RaspberryPiSensorManager
,RaspberryPiTurnoutManager
,RfidReporterManager
,RfidSensorManager
,RpsReporterManager
,RpsSensorManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialLightManager
,SerialSensorManager
,SerialSensorManager
,SerialSensorManager
,SerialSensorManager
,SerialSensorManager
,SerialSensorManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SerialTurnoutManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificLightManager
,SpecificSensorManager
,SpecificSensorManager
,SpecificSensorManager
,SpecificSensorManager
,SprogTurnoutManager
,SRCPSensorManager
,SRCPTurnoutManager
,StandaloneReporterManager
,StandaloneSensorManager
,TamsSensorManager
,TamsTurnoutManager
,TranspondingTagManager
,UsbLightManager
,WarrantManager
,XBeeLightManager
,XBeeSensorManager
,XBeeTurnoutManager
,XNetLightManager
,XNetSensorManager
,XNetTurnoutManager
,XpaTurnoutManager
,Z21ReporterManager
,Z21SensorManager
,Z21XNetTurnoutManager
,ZTC611XNetTurnoutManager
public interface Manager<E extends NamedBean> extends SilenceablePropertyChangeProvider, VetoableChangeProvider
Basic interface for access to named, managed objects.NamedBean
objects represent various real elements, and have a "system name" and perhaps "user name". A specific Manager object provides access to them by name, and serves as a factory for new objects.Right now, this interface just contains the members needed by
InstanceManager
to handle managers for more than one system.Although they are not defined here because their return type differs, any specific Manager subclass provides "get" methods to locate specific objects, and a "new" method to create a new one via the Factory pattern. The "get" methods will return an existing object or null, and will never create a new object. The "new" method will log a warning if an object already exists with that system name.
add/remove PropertyChangeListener methods are provided. At a minimum, subclasses must notify of changes to the list of available NamedBeans; they may have other properties that will also notify.
Probably should have been called NamedBeanManager
This file is part of JMRI.JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.
JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Manager.ManagerDataEvent<E extends NamedBean>
Define an event that encapsulates changes to a list.static interface
Manager.ManagerDataListener<E extends NamedBean>
Intended to be equivalent toListDataListener
without introducing a Swing dependency into core JMRI.static class
Manager.NameValidity
Code the validity (including just as a prefix) of a proposed name string.
-
Field Summary
Fields Modifier and Type Field Description static int
ANALOGIOS
static int
AUDIO
static int
BLOCKBOSS
static int
BLOCKS
static int
CONDITIONALS
static int
CTCDATA
static int
ENTRYEXIT
static int
IDTAGS
static int
LAYOUTBLOCKS
static int
LIGHTS
static int
LOGIXNG_ANALOG_ACTIONS
static int
LOGIXNG_ANALOG_EXPRESSIONS
static int
LOGIXNG_CONDITIONALNGS
static int
LOGIXNG_DIGITAL_ACTIONS
static int
LOGIXNG_DIGITAL_BOOLEAN_ACTIONS
static int
LOGIXNG_DIGITAL_EXPRESSIONS
static int
LOGIXNG_GLOBAL_VARIABLES
static int
LOGIXNG_MODULES
static int
LOGIXNG_STRING_ACTIONS
static int
LOGIXNG_STRING_EXPRESSIONS
static int
LOGIXNG_TABLES
static int
LOGIXNGS
static int
LOGIXS
static int
MEMORIES
static int
METERFRAMES
static int
METERS
static int
OBLOCKS
static int
PANELFILES
static int
REPORTERS
static int
ROUTES
static int
SECTIONS
static int
SENSORGROUPS
static int
SENSORS
The order in which things get saved to the xml file.static int
SIGNALGROUPS
static int
SIGNALHEADS
static int
SIGNALMASTLOGICS
static int
SIGNALMASTS
static int
STRINGIOS
static int
TIMEBASE
static int
TRANSITS
static int
TURNOUTS
static int
WARRANTS
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
addDataListener(Manager.ManagerDataListener<E> e)
Register aManager.ManagerDataListener
to hear about adding or removing items from the list of NamedBeans.void
deleteBean(E n, java.lang.String property)
Method for a UI to delete a bean.void
deregister(E n)
Forget a NamedBean Object created outside the manager.void
dispose()
Free resources when no longer used.default java.lang.String
getBeanTypeHandled()
Get the user-readable name of the type of NamedBean handled by this manager.java.lang.String
getBeanTypeHandled(boolean plural)
Get the user-readable name of the type of NamedBean handled by this manager.E
getBySystemName(java.lang.String systemName)
Locate an existing instance based on a system name.E
getByUserName(java.lang.String userName)
Locate an existing instance based on a user name.default java.lang.String
getEntryToolTip()
Get a manager-specific tool tip for adding an entry to the manager.default java.util.List<NamedBeanPropertyDescriptor<?>>
getKnownBeanProperties()
Return the descriptors for the system-specific properties of the NamedBeans that are kept in this manager.SystemConnectionMemo
getMemo()
Get the system connection for this manager.E
getNamedBean(java.lang.String name)
Locate an existing instance based on a name.java.lang.Class<E>
getNamedBeanClass()
Get the class of NamedBean supported by this Manager.java.util.SortedSet<E>
getNamedBeanSet()
Provide an unmodifiable SortedSet of NamedBeans in system-name order.int
getObjectCount()
Get the count of managed objects.default java.lang.String
getSubSystemNamePrefix()
Get the sub system prefix of this manager.default java.lang.String
getSystemNamePrefix()
Get the prefix and type for the system name of the NamedBeans handled by this manager.java.lang.String
getSystemPrefix()
Provide access to the system prefix string.static java.lang.String
getSystemPrefix(java.lang.String inputName)
Provides the system prefix of the given system name.static int
getSystemPrefixLength(java.lang.String inputName)
Provide length of the system prefix of the given system name.static java.lang.String
getSystemSuffix(java.lang.String inputName)
Provides the suffix (part after the type letter) of the given system name.static java.lang.String
getTypeLetter(java.lang.String inputName)
Provides the type letter of the given system name.int
getXMLOrder()
Determine the order that types should be written when storing panel files.default boolean
isValidSystemNameFormat(java.lang.String systemName)
Test if a given name is in a valid format for this Manager.default java.lang.String
makeSystemName(java.lang.String name)
Create a SystemName by prepending the system name prefix to the name if not already present.default java.lang.String
makeSystemName(java.lang.String name, boolean logErrors)
Create a SystemName by prepending the system name prefix to the name if not already present.default java.lang.String
makeSystemName(java.lang.String name, boolean logErrors, java.util.Locale locale)
Create a SystemName by prepending the system name prefix to the name if not already present.void
register(E n)
Remember a NamedBean Object created outside the manager.void
removeDataListener(Manager.ManagerDataListener<E> e)
Unregister a previously-addedManager.ManagerDataListener
.default void
setDataListenerMute(boolean muted)
Temporarily suppress DataListener notifications.char
typeLetter()
default java.lang.String
validateBadCharsInSystemNameFormat(java.lang.String name, java.util.Locale locale, java.lang.String[] invalidChars)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name has no invalid characters in the string.default java.lang.String
validateIntegerSystemNameFormat(java.lang.String name, int min, int max, java.util.Locale locale)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name is an integer after the prefix.default java.lang.String
validateNmraAccessorySystemNameFormat(java.lang.String name, java.util.Locale locale)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name is a valid NMRA Accessory address after the prefix.default java.lang.String
validateSystemNameFormat(java.lang.String name)
Validate the format of a system name, returning it unchanged if valid.default java.lang.String
validateSystemNameFormat(java.lang.String name, java.util.Locale locale)
Validate the format of name, returning it unchanged if valid.default java.lang.String
validateSystemNameFormatOnlyNumeric(java.lang.String name, java.util.Locale locale)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name String is purely numeric.default java.lang.String
validateSystemNamePrefix(java.lang.String name, java.util.Locale locale)
Basic validation that the system name prefix is correct.default java.lang.String
validateTrimmedMin1NumberSystemNameFormat(java.lang.String name, java.util.Locale locale)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name has has at least 1 number in the String.default java.lang.String
validateTrimmedSystemNameFormat(java.lang.String name, java.util.Locale locale)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name has no trailing white space and no white space between the prefix and suffix.default java.lang.String
validateUppercaseTrimmedSystemNameFormat(java.lang.String name, java.util.Locale locale)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name is upper case and has no trailing white space and not white space between the prefix and suffix.default Manager.NameValidity
validSystemNameFormat(java.lang.String systemName)
Test if parameter is a properly formatted system name.-
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
Methods inherited from interface jmri.beans.SilenceablePropertyChangeProvider
setPropertyChangesSilenced
-
Methods inherited from interface jmri.beans.VetoableChangeProvider
addVetoableChangeListener, addVetoableChangeListener, getVetoableChangeListeners, getVetoableChangeListeners, removeVetoableChangeListener, removeVetoableChangeListener
-
-
-
-
Field Detail
-
SENSORS
static final int SENSORS
The order in which things get saved to the xml file.- See Also:
- Constant Field Values
-
TURNOUTS
static final int TURNOUTS
- See Also:
- Constant Field Values
-
LIGHTS
static final int LIGHTS
- See Also:
- Constant Field Values
-
REPORTERS
static final int REPORTERS
- See Also:
- Constant Field Values
-
MEMORIES
static final int MEMORIES
- See Also:
- Constant Field Values
-
SENSORGROUPS
static final int SENSORGROUPS
- See Also:
- Constant Field Values
-
SIGNALHEADS
static final int SIGNALHEADS
- See Also:
- Constant Field Values
-
SIGNALMASTS
static final int SIGNALMASTS
- See Also:
- Constant Field Values
-
SIGNALGROUPS
static final int SIGNALGROUPS
- See Also:
- Constant Field Values
-
BLOCKS
static final int BLOCKS
- See Also:
- Constant Field Values
-
OBLOCKS
static final int OBLOCKS
- See Also:
- Constant Field Values
-
LAYOUTBLOCKS
static final int LAYOUTBLOCKS
- See Also:
- Constant Field Values
-
SECTIONS
static final int SECTIONS
- See Also:
- Constant Field Values
-
TRANSITS
static final int TRANSITS
- See Also:
- Constant Field Values
-
BLOCKBOSS
static final int BLOCKBOSS
- See Also:
- Constant Field Values
-
ROUTES
static final int ROUTES
- See Also:
- Constant Field Values
-
WARRANTS
static final int WARRANTS
- See Also:
- Constant Field Values
-
SIGNALMASTLOGICS
static final int SIGNALMASTLOGICS
- See Also:
- Constant Field Values
-
IDTAGS
static final int IDTAGS
- See Also:
- Constant Field Values
-
ANALOGIOS
static final int ANALOGIOS
- See Also:
- Constant Field Values
-
METERS
static final int METERS
- See Also:
- Constant Field Values
-
STRINGIOS
static final int STRINGIOS
- See Also:
- Constant Field Values
-
LOGIXS
static final int LOGIXS
- See Also:
- Constant Field Values
-
CONDITIONALS
static final int CONDITIONALS
- See Also:
- Constant Field Values
-
AUDIO
static final int AUDIO
- See Also:
- Constant Field Values
-
TIMEBASE
static final int TIMEBASE
- See Also:
- Constant Field Values
-
LOGIXNGS
static final int LOGIXNGS
- See Also:
- Constant Field Values
-
LOGIXNG_GLOBAL_VARIABLES
static final int LOGIXNG_GLOBAL_VARIABLES
- See Also:
- Constant Field Values
-
LOGIXNG_CONDITIONALNGS
static final int LOGIXNG_CONDITIONALNGS
- See Also:
- Constant Field Values
-
LOGIXNG_MODULES
static final int LOGIXNG_MODULES
- See Also:
- Constant Field Values
-
LOGIXNG_TABLES
static final int LOGIXNG_TABLES
- See Also:
- Constant Field Values
-
LOGIXNG_DIGITAL_EXPRESSIONS
static final int LOGIXNG_DIGITAL_EXPRESSIONS
- See Also:
- Constant Field Values
-
LOGIXNG_DIGITAL_ACTIONS
static final int LOGIXNG_DIGITAL_ACTIONS
- See Also:
- Constant Field Values
-
LOGIXNG_DIGITAL_BOOLEAN_ACTIONS
static final int LOGIXNG_DIGITAL_BOOLEAN_ACTIONS
- See Also:
- Constant Field Values
-
LOGIXNG_ANALOG_EXPRESSIONS
static final int LOGIXNG_ANALOG_EXPRESSIONS
- See Also:
- Constant Field Values
-
LOGIXNG_ANALOG_ACTIONS
static final int LOGIXNG_ANALOG_ACTIONS
- See Also:
- Constant Field Values
-
LOGIXNG_STRING_EXPRESSIONS
static final int LOGIXNG_STRING_EXPRESSIONS
- See Also:
- Constant Field Values
-
LOGIXNG_STRING_ACTIONS
static final int LOGIXNG_STRING_ACTIONS
- See Also:
- Constant Field Values
-
PANELFILES
static final int PANELFILES
- See Also:
- Constant Field Values
-
ENTRYEXIT
static final int ENTRYEXIT
- See Also:
- Constant Field Values
-
METERFRAMES
static final int METERFRAMES
- See Also:
- Constant Field Values
-
CTCDATA
static final int CTCDATA
- See Also:
- Constant Field Values
-
-
Method Detail
-
getMemo
@CheckReturnValue @Nonnull SystemConnectionMemo getMemo()
Get the system connection for this manager.- Returns:
- the system connection for this manager
-
getSystemPrefix
@CheckReturnValue @Nonnull java.lang.String getSystemPrefix()
Provide access to the system prefix string. This was previously called the "System letter"- Returns:
- the system prefix
-
typeLetter
@CheckReturnValue char typeLetter()
- Returns:
- The type letter for a specific implementation
-
getNamedBeanClass
java.lang.Class<E> getNamedBeanClass()
Get the class of NamedBean supported by this Manager. This should be the generic class used in the Manager's class declaration.- Returns:
- the class supported by this Manager.
-
getSystemNamePrefix
default java.lang.String getSystemNamePrefix()
Get the prefix and type for the system name of the NamedBeans handled by this manager.- Returns:
- the prefix generated by concatenating the result of
getSystemPrefix()
andtypeLetter()
-
getSubSystemNamePrefix
default java.lang.String getSubSystemNamePrefix()
Get the sub system prefix of this manager. The sub system prefix is the system name prefix and possibly some extra characters of the NamedBeans handled by this manager.For most managers, this is the same as
getSystemNamePrefix()
, but for some like the managers in LogixNG, it differs.- Returns:
- the sub system prefix
-
makeSystemName
@Nonnull default java.lang.String makeSystemName(@Nonnull java.lang.String name) throws NamedBean.BadSystemNameException
Create a SystemName by prepending the system name prefix to the name if not already present.Note: implementations must call
validateSystemNameFormat(java.lang.String, java.util.Locale)
to ensure the returned name is valid.- Parameters:
name
- the item to make the system name for- Returns:
- A system name from a user input, typically a number.
- Throws:
NamedBean.BadSystemNameException
- if a valid name can't be created
-
makeSystemName
@Nonnull default java.lang.String makeSystemName(@Nonnull java.lang.String name, boolean logErrors) throws NamedBean.BadSystemNameException
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
validateSystemNameFormat(java.lang.String, java.util.Locale)
to ensure the returned name is valid.- Parameters:
name
- the item to make the system name forlogErrors
- true to log errors; false to not log errors- Returns:
- a valid system name
- Throws:
NamedBean.BadSystemNameException
- if a valid name can't be created
-
makeSystemName
@Nonnull default java.lang.String makeSystemName(@Nonnull java.lang.String name, boolean logErrors, java.util.Locale locale) throws NamedBean.BadSystemNameException
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
validateSystemNameFormat(java.lang.String, java.util.Locale)
to ensure the returned name is valid.- Parameters:
name
- 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
- Throws:
NamedBean.BadSystemNameException
- if a valid name can't be created
-
validateSystemNameFormat
@Nonnull default java.lang.String validateSystemNameFormat(@Nonnull java.lang.String name) throws NamedBean.BadSystemNameException
Validate the format of a system name, returning it unchanged if valid.This is a convenience form of
validateSystemNameFormat(java.lang.String, java.util.Locale)
.This method should not be overridden;
validateSystemNameFormat(java.lang.String, java.util.Locale)
should be overridden instead.- Parameters:
name
- the system name, including system prefix and Type Letter to validate- Returns:
- the system name unchanged from its input so that this method can be chained or used as an parameter to another method
- Throws:
NamedBean.BadSystemNameException
- if the name is not valid with error messages in the default locale
-
validateSystemNameFormat
@Nonnull default java.lang.String validateSystemNameFormat(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale) throws NamedBean.BadSystemNameException
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
validSystemNameFormat(java.lang.String)
, however they must provide an actionable message in the thrown exception if that method does not returnManager.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.- Parameters:
name
- the system name to validatelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateSystemNamePrefix
@Nonnull default java.lang.String validateSystemNamePrefix(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale) throws NamedBean.BadSystemNameException
Basic validation that the system name prefix is correct. Used within the default implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
and abstracted out of that method so this can be used by validation implementations inSystemConnectionMemo
s to avoid duplicating code in all managers relying on a single subclass of SystemConnectionMemo.- Parameters:
name
- the system name to validatelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateTrimmedSystemNameFormat
@Nonnull default java.lang.String validateTrimmedSystemNameFormat(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale) throws NamedBean.BadSystemNameException
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name has no trailing white space and no white space between the prefix and suffix.Note this must only be used if the connection type is externally documented to require these restrictions.
- Parameters:
name
- the system name to validatelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateTrimmedMin1NumberSystemNameFormat
@Nonnull default java.lang.String validateTrimmedMin1NumberSystemNameFormat(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale) throws NamedBean.BadSystemNameException
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name has has at least 1 number in the String.- Parameters:
name
- the system name to validatelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateSystemNameFormatOnlyNumeric
default java.lang.String validateSystemNameFormatOnlyNumeric(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale)
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name String is purely numeric.- Parameters:
name
- the system name to validatelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateBadCharsInSystemNameFormat
@Nonnull default java.lang.String validateBadCharsInSystemNameFormat(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale, @Nonnull java.lang.String[] invalidChars) throws NamedBean.BadSystemNameException
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name has no invalid characters in the string.Also checks validateSystemNamePrefix(name,locale);
- Parameters:
name
- the system name to validatelocale
- the locale for a localized exception; this is needed for the JMRI web server, which supports multiple localesinvalidChars
- array of invalid characters which cannot be in the system name.- Returns:
- the unchanged value of the name parameter
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateUppercaseTrimmedSystemNameFormat
@Nonnull default java.lang.String validateUppercaseTrimmedSystemNameFormat(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale) throws NamedBean.BadSystemNameException
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name is upper case and has no trailing white space and not white space between the prefix and suffix.Note this must only be used if the connection type is externally documented to require these restrictions.
- Parameters:
name
- the system name to validatelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateIntegerSystemNameFormat
@Nonnull default java.lang.String validateIntegerSystemNameFormat(@Nonnull java.lang.String name, int min, int max, @Nonnull java.util.Locale locale) throws NamedBean.BadSystemNameException
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name is an integer after the prefix.Note this must only be used if the connection type is externally documented to require these restrictions.
- Parameters:
name
- the system name to validatemin
- the minimum valid integer valuemax
- the maximum valid integer valuelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validateNmraAccessorySystemNameFormat
@Nonnull default java.lang.String validateNmraAccessorySystemNameFormat(@Nonnull java.lang.String name, @Nonnull java.util.Locale locale) throws NamedBean.BadSystemNameException
Convenience implementation ofvalidateSystemNameFormat(java.lang.String, java.util.Locale)
that verifies name is a valid NMRA Accessory address after the prefix. A name is considered a valid NMRA accessory address if it is an integer between 1 and 2044, inclusive.Note this must only be used if the connection type is externally documented to require these restrictions.
- Parameters:
name
- the system name to validatelocale
- 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
- Throws:
NamedBean.BadSystemNameException
- if provided name is an invalid format
-
validSystemNameFormat
@CheckReturnValue @OverrideMustInvoke default Manager.NameValidity validSystemNameFormat(@Nonnull java.lang.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.- Parameters:
systemName
- the system name- Returns:
- enum indicating current validity, which might be just as a prefix
- Since:
- 4.9.5, although similar methods existed previously in lower-level classes
-
isValidSystemNameFormat
default boolean isValidSystemNameFormat(@Nonnull java.lang.String systemName)
Test if a given name is in a valid format for this Manager.- Parameters:
systemName
- the name to check- Returns:
true
ifvalidSystemNameFormat(java.lang.String)
equalsManager.NameValidity.VALID
;false
otherwise
-
dispose
void dispose()
Free resources when no longer used. Specifically, remove all references to and from this object, so it can be garbage-collected.
-
getObjectCount
@CheckReturnValue int getObjectCount()
Get the count of managed objects.- Returns:
- the number of managed objects
-
getNamedBeanSet
@CheckReturnValue @Nonnull 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
- Returns:
- Unmodifiable access to a SortedSet of NamedBeans
-
getBySystemName
@CheckReturnValue @CheckForNull E getBySystemName(@Nonnull java.lang.String systemName)
Locate an existing instance based on a system name.- Parameters:
systemName
- System Name of the required NamedBean- Returns:
- requested NamedBean object or null if none exists
- Throws:
java.lang.IllegalArgumentException
- if provided name is invalid
-
getByUserName
@CheckReturnValue @CheckForNull E getByUserName(@Nonnull java.lang.String userName)
Locate an existing instance based on a user name.- Parameters:
userName
- System Name of the required NamedBean- Returns:
- requested NamedBean object or null if none exists
-
getNamedBean
@CheckReturnValue @CheckForNull E getNamedBean(@Nonnull java.lang.String name)
Locate an existing instance based on a name.- Parameters:
name
- User Name or System Name of the required NamedBean- Returns:
- requested NamedBean object or null if none exists
-
getKnownBeanProperties
@Nonnull default java.util.List<NamedBeanPropertyDescriptor<?>> getKnownBeanProperties()
Return the descriptors for the system-specific properties of the NamedBeans that are kept in this manager.- Returns:
- list of known properties, or empty list if there are none
-
deleteBean
void deleteBean(@Nonnull E n, @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.
- Parameters:
n
- 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:
java.beans.PropertyVetoException
- If the recipients wishes the delete to be aborted (see above)
-
register
void register(@Nonnull E n)
Remember a NamedBean Object created outside the manager.The non-system-specific SignalHeadManagers use this method extensively.
- Parameters:
n
- the bean- Throws:
NamedBean.DuplicateSystemNameException
- if a different bean with the same system name is already registered in the manager
-
deregister
void deregister(@Nonnull E n)
Forget a NamedBean Object created outside the manager.The non-system-specific RouteManager uses this method.
- Parameters:
n
- the bean
-
getXMLOrder
@CheckReturnValue int getXMLOrder()
Determine the order that types should be written when storing panel files. Uses one of the constants defined in this class.Yes, that's an overly-centralized methodology, but it works for now.
- Returns:
- write order for this Manager; larger is later.
-
getBeanTypeHandled
@CheckReturnValue @Nonnull default java.lang.String getBeanTypeHandled()
Get the user-readable name of the type of NamedBean handled by this manager.For instance, in the code where we are dealing with just a bean and a message that needs to be passed to the user or in a log.
- Returns:
- a string of the bean type that the manager handles, eg Turnout, Sensor etc
-
getBeanTypeHandled
@CheckReturnValue @Nonnull java.lang.String getBeanTypeHandled(boolean plural)
Get the user-readable name of the type of NamedBean handled by this manager.For instance, in the code where we are dealing with just a bean and a message that needs to be passed to the user or in a log.
- Parameters:
plural
- true to return plural form of the type; false to return singular form- Returns:
- a string of the bean type that the manager handles, eg Turnout, Sensor etc
-
getSystemPrefixLength
@CheckReturnValue static int getSystemPrefixLength(@Nonnull java.lang.String inputName)
Provide length of the system prefix of the given system name.This is a common operation across JMRI, as the system prefix can be parsed out without knowledge of the type of NamedBean involved.
- Parameters:
inputName
- System Name to provide the prefix- Returns:
- The length of the system-prefix part of the system name in standard normalized form
- Throws:
NamedBean.BadSystemNameException
- If the inputName is not in normalized form
-
getSystemPrefix
@CheckReturnValue @Nonnull static java.lang.String getSystemPrefix(@Nonnull java.lang.String inputName)
Provides the system prefix of the given system name.This is a common operation across JMRI, as the system prefix can be parsed out without knowledge of the type of NamedBean involved.
- Parameters:
inputName
- System name to provide the prefix- Returns:
- The system-prefix part of the system name in standard normalized form
- Throws:
NamedBean.BadSystemNameException
- If the inputName is not in normalized form
-
getTypeLetter
@CheckReturnValue @Nonnull static java.lang.String getTypeLetter(@Nonnull java.lang.String inputName)
Provides the type letter of the given system name.This is a common operation across JMRI, as the system prefix can be parsed out without knowledge of the type of NamedBean involved.
- Parameters:
inputName
- System name to provide the type letter- Returns:
- The type letter of the system name
- Throws:
NamedBean.BadSystemNameException
- If the inputName is not in normalized form
-
getSystemSuffix
@CheckReturnValue @Nonnull static java.lang.String getSystemSuffix(@Nonnull java.lang.String inputName)
Provides the suffix (part after the type letter) of the given system name.This is a common operation across JMRI, as the system prefix can be parsed out without knowledge of the type of NamedBean involved.
- Parameters:
inputName
- System name to provide the suffix- Returns:
- The suffix part of the system name
- Throws:
NamedBean.BadSystemNameException
- If the inputName is not in normalized form
-
getEntryToolTip
default java.lang.String getEntryToolTip()
Get a manager-specific tool tip for adding an entry to the manager.- Returns:
- the tool tip or null to disable the tool tip
-
addDataListener
void addDataListener(Manager.ManagerDataListener<E> e)
Register aManager.ManagerDataListener
to hear about adding or removing items from the list of NamedBeans.- Parameters:
e
- the data listener to add
-
removeDataListener
void removeDataListener(Manager.ManagerDataListener<E> e)
Unregister a previously-addedManager.ManagerDataListener
.- Parameters:
e
- the data listener to remove- See Also:
addDataListener(ManagerDataListener)
-
setDataListenerMute
default void setDataListenerMute(boolean muted)
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.
- Parameters:
muted
- true if notifications should be suppressed; false otherwise
-
-