Package jmri

Class InstanceManager

  • public final class InstanceManager
extends java.lang.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 Detail

      • InstanceManager

        public InstanceManager()
        Default constructor for the InstanceManager.

    • Method Detail

      • store

        public static <T> void store​(@Nonnull
                             T item,
                             @Nonnull
                             java.lang.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
                                      java.lang.Object item,
                                      @Nonnull
                                      java.lang.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> java.util.List<T> getList​(@Nonnull
                                            java.lang.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 java.util.List<java.lang.Object> getList​(@Nonnull
                                                       java.lang.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:
        java.lang.IllegalArgumentException - if the named class doesn't exist

      • reset

        public static <T> void reset​(@Nonnull
                             java.lang.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.

      • remove

        public <T> void remove​(@Nonnull
                       T item,
                       @Nonnull
                       java.lang.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

      • getNullableDefault

        @CheckForNull
public static java.lang.Object getNullableDefault​(@Nonnull
                                                  java.lang.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:
        java.lang.IllegalArgumentException - if the named class doesn't exist
        See Also:
        getOptionalDefault(java.lang.Class)

      • getOptionalDefault

        @Nonnull
public static <T> java.util.Optional<T> getOptionalDefault​(@Nonnull
                                                           java.lang.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
                               java.lang.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
                                          java.lang.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
                                        java.lang.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 java.lang.String contentsToString()
        Dump generic content of InstanceManager by type.
        Returns:
        A formatted multiline list of managed objects

      • getInstanceClasses

        public static java.util.Set<java.lang.Class<?>> getInstanceClasses()
        Get a list of stored types
        Returns:
        A unmodifiable list of the currently stored types

      • removePropertyChangeListener

        public static void removePropertyChangeListener​(java.beans.PropertyChangeListener l)
        Remove notification on changes to specific types.
        Parameters:
        l - The listener to remove

      • removePropertyChangeListener

        public static void removePropertyChangeListener​(java.lang.String propertyName,
                                                java.beans.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​(java.beans.PropertyChangeListener l)
        Register for notification on changes to specific types.
        Parameters:
        l - The listener to add

      • addPropertyChangeListener

        public static void addPropertyChangeListener​(java.lang.String propertyName,
                                             java.beans.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 java.lang.String getDefaultsPropertyName​(java.lang.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 java.lang.String getListPropertyName​(java.lang.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.

      • getInstances

        @Nonnull
public <T> java.util.List<T> getInstances​(@Nonnull
                                          java.lang.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> java.util.List<T> getInstances​(@Nonnull
                                          java.lang.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:
        java.lang.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
                      java.lang.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