Package jmri.spi

Interface PreferencesManager

All Superinterfaces:
JmriServiceProviderInterface
All Known Implementing Classes:
AbstractPreferencesManager, ConnectionConfigManager, ConsistPreferencesManager, FileLocationsPreferences, GuiLafPreferencesManager, GuiLafPreferencesManager, JmriJTablePersistenceManager, ManagerDefaultSelector, ProgrammerConfigManager, RosterConfigManager, StartupActionsManager, StartupActionsManager, SystemConsolePreferencesManager, WarrantPreferences, WebAppManager
public interface PreferencesManager
extends JmriServiceProviderInterface
An API for Java Service Providers that manage preferences within JMRI. It is strongly recommended that PreferencesManagers use JmriConfigurationProvider or JmriPreferencesProvider to store preferences.

PreferencesManagers must provide a default public constructor, but must also not perform any initialization until initialize(jmri.profile.Profile) is called as the PreferencesManager may be constructed before the Profile is known.

AbstractPreferencesManager provides an abstract implementation that is ready to extend.

See Also:
AbstractPreferencesManager

  • Method Details

    • initialize

      void initialize​(Profile profile) throws InitializationException
      Initialize the PreferencesManager with preferences associated with the provided Profile.

      Implementing classes should throw an InitializationException with a user readable localized message, since it most likely be displayed to the user. Implementing classes will still want to ensure that isInitialized(jmri.profile.Profile) or isInitializedWithExceptions(jmri.profile.Profile) return true if throwing an InitializationException to ensure that the provider is not repeatedly initialized.

      Parameters:
      profile - the configuration profile used for this initialization; may be null to initialize for this user regardless of profile
      Throws:
      InitializationException - if the user needs to be notified of an issue that prevents regular use of the application

    • isInitialized

      boolean isInitialized​(Profile profile)
      Test if the PreferencesManager is initialized without errors for the provided Profile. Note that although both this method and isInitializedWithExceptions(jmri.profile.Profile) can be false, if isInitializedWithExceptions(Profile) returns true, this method must return false.
      Parameters:
      profile - the configuration profile to test against; may be null to test for exceptions thrown when initializing for this user regardless of profile
      Returns:
      true if the provider is initialized without exceptions

    • isInitializedWithExceptions

      boolean isInitializedWithExceptions​(Profile profile)
      Test if the PreferencesManager is initialized, but threw an InitializationException during initialization, for the provided Profile. Note that although both this method and isInitialized(jmri.profile.Profile) can be false, if isInitialized(Profile) returns true, this method must return false.
      Parameters:
      profile - the configuration profile to test against; may be null to test for exceptions thrown when initializing for this user regardless of profile
      Returns:
      true if the provide is initialized with exceptions

    • getInitializationExceptions

      @Nonnull List<Exception> getInitializationExceptions​(Profile profile)
      Get the set of exceptions thrown during initialization for the provided Profile.
      Parameters:
      profile - the configuration profile to test against; may be null to test for exceptions thrown when initializing for this user regardless of profile
      Returns:
      A list of exceptions. If there are no exceptions, return an empty set instead of null.

    • getRequires

      @Nonnull Collection<Class<? extends PreferencesManager>> getRequires()
      Get the set of PreferencesManagers that must be initialized prior to initializing this PreferencesManager. It is generally preferable to require an Interface or an abstract Class instead of a concrete Class, since that allows all (or any) concrete implementations of the required class to be initialized to provide required services for the requiring PreferencesManager instance.

      Note that for any set of PreferencesManagers with the same requirements, or with a circular dependency between each other, the order in which the PreferencesManagers in that set are initialized should be considered non-deterministic.

      Returns:
      A set or list of classes. If there are no dependencies, return an empty set instead of null.

    • getProvides

      @Nonnull Iterable<Class<?>> getProvides()
      Get the set of Classes that this PreferencesManager can be registered as a provider of in the InstanceManager.
      Returns:
      A set or list of classes. If this PreferencesManager provides an instance of no other Interfaces or abstract Classes than PreferencesManager, return an empty set instead of null.

    • savePreferences

      void savePreferences​(Profile profile)
      Save the preferences that this provider manages for the provided Profile.
      Parameters:
      profile - the profile associated with the preferences to save; may be null to save preferences that apply to the current user regardless of profile