Package jmri

Class InstanceManager

java.lang.Object

jmri.InstanceManager

public final class InstanceManager
extends Object

Provides methods for locating various interface implementations. These form the base for locating JMRI objects, including the key managers.

The structural goal is to have the jmri package not depend on lower packages, with the implementations still available at run-time through the InstanceManager.

To retrieve the default object of a specific type, do getDefault(java.lang.Class<T>) where the argument is e.g. "SensorManager.class". In other words, you ask for the default object of a particular type. Note that this call is intended to be used in the usual case of requiring the object to function; it will log a message if there isn't such an object. If that's routine, then use the getNullableDefault(java.lang.Class<T>) method instead.

Multiple items can be held, and are retrieved as a list with getList(java.lang.Class<T>).

If a specific item is needed, e.g. one that has been constructed via a complex process during startup, it should be installed with store(T, java.lang.Class<T>).

If it is desirable for the InstanceManager to create an object on first request, have that object's class implement the InstanceManagerAutoDefault flag interface. The InstanceManager will then construct a default object via the no-argument constructor when one is first requested.

For initialization of more complex default objects, see the InstanceInitializer mechanism and its default implementation in DefaultInstanceInitializer.

Implement the InstanceManagerAutoInitialize interface when default objects need to be initialized after the default instance has been constructed and registered with the InstanceManager. This will allow references to the default instance during initialization to work as expected.

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.

Constructor Summary

Constructors

Constructor	Description
InstanceManager()	Default constructor for the InstanceManager.

Method Summary

Modifier and Type	Method	Description
static void	addPropertyChangeListener(PropertyChangeListener l)	Register for notification on changes to specific types.
static void	addPropertyChangeListener(String propertyName, PropertyChangeListener l)	Register for notification on changes to specific types
<T> void	clear(Class<T> type)	Clear all managed instances of a particular type from this InstanceManager.
void	clearAll()	Clear all managed instances from the common instance manager, effectively installing a new one.
static <T> boolean	containsDefault(Class<T> type)	Check if a default has been set for the given type.
static String	contentsToString()	Dump generic content of InstanceManager by type.
static <T> void	deregister(T item, Class<T> type)	Remove an object of a particular type that had earlier been registered with store(T, java.lang.Class<T>).
static InstanceManager	getDefault()	Get the default instance of the InstanceManager.
static <T> T	getDefault(Class<T> type)	Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class).
static Object	getDefault(String className)	Retrieve the last object of specific type that was registered with store(java.lang.Object, java.lang.Class).
static String	getDefaultsPropertyName(Class<?> clazz)	Get the property name included in the PropertyChangeEvent thrown when the default for a specific class is changed.
<T> T	getInstance(Class<T> type)	Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class).
static Set<Class<?>>	getInstanceClasses()	Get a list of stored types
<T> List<T>	getInstances(Class<T> type)	Get a list of all registered objects of type T.
<T> List<T>	getInstances(String className)	Get a list of all registered objects of a specific type.
static <T> List<T>	getList(Class<T> type)	Retrieve a list of all objects of type T that were registered with store(T, java.lang.Class<T>).
static List<Object>	getList(String className)	Retrieve a list of all objects of a specific type that were registered with store(T, java.lang.Class<T>).
static String	getListPropertyName(Class<?> clazz)	Get the property name included in the PropertyChangeEvent thrown when the list for a specific class is changed.
static <T> T	getNullableDefault(Class<T> type)	Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class).
static Object	getNullableDefault(String className)	Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class).
static <T> Optional<T>	getOptionalDefault(Class<T> type)	Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class) wrapped in an Optional.
static <T> boolean	isInitialized(Class<T> type)	Check if a particular type has been initialized without triggering an automatic initialization.
static LightManager	lightManagerInstance()	May eventually be deprecated, use @{link #getDefault} directly.
static MemoryManager	memoryManagerInstance()	May eventually be deprecated, use @{link #getDefault} directly.
<T> void	remove(T item, Class<T> type)	Remove an object of a particular type that had earlier been registered with store(T, java.lang.Class<T>).
static void	removePropertyChangeListener(PropertyChangeListener l)	Remove notification on changes to specific types.
static void	removePropertyChangeListener(String propertyName, PropertyChangeListener l)	Remove notification on changes to specific types.
static <T> void	reset(Class<T> type)	Deregister all objects of a particular type.
static SensorManager	sensorManagerInstance()	May eventually be deprecated, use @{link #getDefault} directly.
static void	setAnalogIOManager(AnalogIOManager p)
static <T> T	setDefault(Class<T> type, T item)	Set an object of type T as the default for that type.
static void	setIdTagManager(IdTagManager p)
static void	setLightManager(LightManager p)
static void	setMeterManager(MeterManager p)
static void	setReporterManager(ReporterManager p)
static void	setSensorManager(SensorManager p)
static void	setStringIOManager(StringIOManager p)
static void	setThrottleManager(ThrottleManager p)
static void	setTurnoutManager(TurnoutManager p)
static <T> void	store(T item, Class<T> type)	Store an object of a particular type for later retrieval via getDefault(java.lang.Class<T>) or getList(java.lang.Class<T>).
static <T> void	storeUnchecked(Object item, Class<T> type)	Store an object of a particular type for later retrieval via getDefault(java.lang.Class<T>) or getList(java.lang.Class<T>).
static ThrottleManager	throttleManagerInstance()	May eventually be deprecated, use @{link #getDefault} directly.
static TurnoutManager	turnoutManagerInstance()	May eventually be deprecated, use @{link #getDefault} directly.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

InstanceManager

public InstanceManager()

Default constructor for the InstanceManager.

Method Details

store

public static <T> void store(@Nonnull
 T item,
 @Nonnull
 Class<T> type)

Store an object of a particular type for later retrieval via getDefault(java.lang.Class<T>) or getList(java.lang.Class<T>).

Type Parameters:

T - The type of the class

Parameters:

item - The object of type T to be stored

type - The class Object for the item's type. This will be used as the key to retrieve the object later.

storeUnchecked

public static <T> void storeUnchecked(@Nonnull
 Object item,
 @Nonnull
 Class<T> type)

Store an object of a particular type for later retrieval via getDefault(java.lang.Class<T>) or getList(java.lang.Class<T>).

store(T, java.lang.Class<T>) is preferred to this method because it does type checking at compile time. In (rare) cases that's not possible, and run-time checking is required.

Type Parameters:

T - The type of the class

Parameters:

item - The object of type T to be stored

type - The class Object for the item's type. This will be used as the key to retrieve the object later.

getList

@Nonnull
public static <T> List<T> getList(@Nonnull
 Class<T> type)

Retrieve a list of all objects of type T that were registered with store(T, java.lang.Class<T>).

Type Parameters:

T - The type of the class

Parameters:

type - The class Object for the items' type.

Returns:

A list of type Objects registered with the manager or an empty list.

getList

@Nonnull
public static List<Object> getList(@Nonnull
 String className)

Retrieve a list of all objects of a specific type that were registered with store(T, java.lang.Class<T>). Intended for use with i.e. scripts where access to the class type is inconvenient. In Java code where typing is enforced, use getList(Class).

Parameters:

className - Fully qualified class name

Returns:

A list of type Objects registered with the manager or an empty list.

Throws:

IllegalArgumentException - if the named class doesn't exist

reset

public static <T> void reset(@Nonnull
 Class<T> type)

Deregister all objects of a particular type.

Type Parameters:

T - The type of the class

Parameters:

type - The class Object for the items to be removed.

deregister

public static <T> void deregister(@Nonnull
 T item,
 @Nonnull
 Class<T> type)

Remove an object of a particular type that had earlier been registered with store(T, java.lang.Class<T>). If item was previously registered, this will remove item and fire an indexed property change event for the property matching the output of getListPropertyName(java.lang.Class) for type.

This is the static access to remove(java.lang.Object, java.lang.Class).

Type Parameters:

T - The type of the class

Parameters:

item - The object of type T to be deregistered

type - The class Object for the item's type

remove

public <T> void remove(@Nonnull
 T item,
 @Nonnull
 Class<T> type)

Remove an object of a particular type that had earlier been registered with store(T, java.lang.Class<T>). If item was previously registered, this will remove item and fire an indexed property change event for the property matching the output of getListPropertyName(java.lang.Class) for type.

Type Parameters:

T - The type of the class

Parameters:

item - The object of type T to be deregistered

type - The class Object for the item's type

getDefault

@Nonnull
public static <T> T getDefault(@Nonnull
 Class<T> type)

Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class).

Unless specifically set, the default is the last object stored, see the setDefault(java.lang.Class, java.lang.Object) method.

In some cases, InstanceManager can create the object the first time it's requested. For more on that, see the class comment.

In most cases, system configuration assures the existence of a default object, so this method will log and throw an exception if one doesn't exist. Use getNullableDefault(java.lang.Class) or getOptionalDefault(java.lang.Class) if the default is not guaranteed to exist.

Type Parameters:

T - The type of the class

Parameters:

type - The class Object for the item's type

Returns:

The default object for type

Throws:

NullPointerException - if no default object for type exists

See Also:

• getNullableDefault(java.lang.Class)
• getOptionalDefault(java.lang.Class)

getDefault

@Nonnull
public static Object getDefault(@Nonnull
 String className)

Retrieve the last object of specific type that was registered with store(java.lang.Object, java.lang.Class). Intended for use with i.e. scripts where access to the class type is inconvenient. In Java code where typing is enforced, use getDefault(Class).

Unless specifically set, the default is the last object stored, see the setDefault(java.lang.Class, java.lang.Object) method.

In some cases, InstanceManager can create the object the first time it's requested. For more on that, see the class comment.

In most cases, system configuration assures the existence of a default object, so this method will log and throw an exception if one doesn't exist. Use getNullableDefault(java.lang.Class) or getOptionalDefault(java.lang.Class) if the default is not guaranteed to exist.

Parameters:

className - Fully qualified class name

Returns:

The default object for type

Throws:

NullPointerException - if no default object for type exists

IllegalArgumentException - if the named class doesn't exist

See Also:

• getNullableDefault(java.lang.Class)
• getOptionalDefault(java.lang.Class)

getNullableDefault

@CheckForNull
public static <T> T getNullableDefault(@Nonnull
 Class<T> type)

Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class).

Unless specifically set, the default is the last object stored, see the setDefault(java.lang.Class, java.lang.Object) method.

In some cases, InstanceManager can create the object the first time it's requested. For more on that, see the class comment.

In most cases, system configuration assures the existence of a default object, but this method also handles the case where one doesn't exist. Use getDefault(java.lang.Class) when the object is guaranteed to exist.

Type Parameters:

T - The type of the class

Parameters:

type - The class Object for the item's type.

Returns:

The default object for type.

See Also:

• getOptionalDefault(java.lang.Class)

getNullableDefault

@CheckForNull
public static Object getNullableDefault(@Nonnull
 String className)

Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class). Intended for use with i.e. scripts where access to the class type is inconvenient. In Java code where typing is enforced, use getNullableDefault(Class).

Unless specifically set, the default is the last object stored, see the setDefault(java.lang.Class, java.lang.Object) method.

In some cases, InstanceManager can create the object the first time it's requested. For more on that, see the class comment.

In most cases, system configuration assures the existence of a default object, but this method also handles the case where one doesn't exist. Use getDefault(java.lang.Class) when the object is guaranteed to exist.

Parameters:

className - Fully qualified class name

Returns:

The default object for type.

Throws:

IllegalArgumentException - if the named class doesn't exist

See Also:

• getOptionalDefault(java.lang.Class)

getInstance

@CheckForNull
public <T> T getInstance(@Nonnull
 Class<T> type)

Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class).

Unless specifically set, the default is the last object stored, see the setDefault(java.lang.Class, java.lang.Object) method.

In some cases, InstanceManager can create the object the first time it's requested. For more on that, see the class comment.

In most cases, system configuration assures the existence of a default object, but this method also handles the case where one doesn't exist. Use getDefault(java.lang.Class) when the object is guaranteed to exist.

Type Parameters:

T - The type of the class

Parameters:

type - The class Object for the item's type.

Returns:

The default object for type.

See Also:

• getOptionalDefault(java.lang.Class)

getOptionalDefault

@Nonnull
public static <T> Optional<T> getOptionalDefault(@Nonnull
 Class<T> type)

Retrieve the last object of type T that was registered with store(java.lang.Object, java.lang.Class) wrapped in an Optional.

Unless specifically set, the default is the last object stored, see the setDefault(java.lang.Class, java.lang.Object) method.

In some cases, InstanceManager can create the object the first time it's requested. For more on that, see the class comment.

In most cases, system configuration assures the existence of a default object, but this method also handles the case where one doesn't exist. Use getDefault(java.lang.Class) when the object is guaranteed to exist.

Type Parameters:

T - the type of the default class

Parameters:

type - the class Object for the default type

Returns:

the default wrapped in an Optional or an empty Optional if the default is null

See Also:

• getNullableDefault(java.lang.Class)

setDefault

@Nonnull
public static <T> T setDefault(@Nonnull
 Class<T> type,
 @Nonnull
 T item)

Set an object of type T as the default for that type.

Also registers (stores) the object if not already present.

Now, we do that moving the item to the back of the list; see the getDefault(java.lang.Class<T>) method

Type Parameters:

T - The type of the class

Parameters:

type - The Class object for val

item - The object to make default for type

Returns:

The default for type (normally this is the item passed in)

containsDefault

public static <T> boolean containsDefault(@Nonnull
 Class<T> type)

Check if a default has been set for the given type.

As a side-effect, then (a) ensures that the list for the given type exists, though it may be empty, and (b) if it had to create the list, a PropertyChangeEvent is fired to denote that.

Type Parameters:

T - The type of the class

Parameters:

type - The class type

Returns:

true if an item is available as a default for the given type; false otherwise

isInitialized

public static <T> boolean isInitialized(@Nonnull
 Class<T> type)

Check if a particular type has been initialized without triggering an automatic initialization. The existence or non-existence of the corresponding list is not changed, and no PropertyChangeEvent is fired.

Type Parameters:

T - The type of the class

Parameters:

type - The class type

Returns:

true if an item is available as a default for the given type; false otherwise

contentsToString

@Nonnull
public static String contentsToString()

Dump generic content of InstanceManager by type.

Returns:

A formatted multiline list of managed objects

getInstanceClasses

public static Set<Class<?>> getInstanceClasses()

Get a list of stored types

Returns:

A unmodifiable list of the currently stored types

removePropertyChangeListener

public static void removePropertyChangeListener(PropertyChangeListener l)

Remove notification on changes to specific types.

Parameters:

l - The listener to remove

removePropertyChangeListener

public static void removePropertyChangeListener(String propertyName,
 PropertyChangeListener l)

Remove notification on changes to specific types.

Parameters:

propertyName - the property being listened for

l - The listener to remove

addPropertyChangeListener

public static void addPropertyChangeListener(PropertyChangeListener l)

Register for notification on changes to specific types.

Parameters:

l - The listener to add

addPropertyChangeListener

public static void addPropertyChangeListener(String propertyName,
 PropertyChangeListener l)

Register for notification on changes to specific types

Parameters:

propertyName - the property being listened for

l - The listener to add

getDefaultsPropertyName

public static String getDefaultsPropertyName(Class<?> clazz)

Get the property name included in the PropertyChangeEvent thrown when the default for a specific class is changed.

Parameters:

clazz - the class being listened for

Returns:

the property name

getListPropertyName

public static String getListPropertyName(Class<?> clazz)

Get the property name included in the PropertyChangeEvent thrown when the list for a specific class is changed.

Parameters:

clazz - the class being listened for

Returns:

the property name

lightManagerInstance

public static LightManager lightManagerInstance()

May eventually be deprecated, use @{link #getDefault} directly.

Returns:

the default light manager. May not be the only instance.

memoryManagerInstance

public static MemoryManager memoryManagerInstance()

May eventually be deprecated, use @{link #getDefault} directly.

Returns:

the default memory manager. May not be the only instance.

sensorManagerInstance

public static SensorManager sensorManagerInstance()

May eventually be deprecated, use @{link #getDefault} directly.

Returns:

the default sensor manager. May not be the only instance.

turnoutManagerInstance

public static TurnoutManager turnoutManagerInstance()

May eventually be deprecated, use @{link #getDefault} directly.

Returns:

the default turnout manager. May not be the only instance.

throttleManagerInstance

public static ThrottleManager throttleManagerInstance()

May eventually be deprecated, use @{link #getDefault} directly.

Returns:

the default throttle manager. May not be the only instance.

setTurnoutManager

public static void setTurnoutManager(TurnoutManager p)

setThrottleManager

public static void setThrottleManager(ThrottleManager p)

setLightManager

public static void setLightManager(LightManager p)

setReporterManager

public static void setReporterManager(ReporterManager p)

setSensorManager

public static void setSensorManager(SensorManager p)

setIdTagManager

public static void setIdTagManager(IdTagManager p)

setMeterManager

public static void setMeterManager(MeterManager p)

setAnalogIOManager

public static void setAnalogIOManager(AnalogIOManager p)

setStringIOManager

public static void setStringIOManager(StringIOManager p)

getInstances

@Nonnull
public <T> List<T> getInstances(@Nonnull
 Class<T> type)

Get a list of all registered objects of type T.

Type Parameters:

T - type of the class

Parameters:

type - class Object for type T

Returns:

a list of registered T instances with the manager or an empty list

getInstances

@Nonnull
public <T> List<T> getInstances(@Nonnull
 String className)

Get a list of all registered objects of a specific type. Intended for use with i.e. scripts where access to the class type is inconvenient.

Type Parameters:

T - type of the class

Parameters:

className - Fully qualified class name

Returns:

a list of registered instances with the manager or an empty list

Throws:

IllegalArgumentException - if the named class doesn't exist

clearAll

public void clearAll()

Clear all managed instances from the common instance manager, effectively installing a new one.

clear

public <T> void clear(@Nonnull
 Class<T> type)

Clear all managed instances of a particular type from this InstanceManager.

Type Parameters:

T - the type of class to clear

Parameters:

type - the type to clear

getDefault

@Nonnull
public static InstanceManager getDefault()

Get the default instance of the InstanceManager. This is used for verifying the source of events fired by the InstanceManager.

Returns:

the default instance of the InstanceManager, creating it if needed