Package jmri.profile

Class ProfileManager

    • Constructor Detail

      • ProfileManager

        public ProfileManager()
        Create a new ProfileManager using the default catalog. In almost all cases, the use of getDefault() is preferred.

      • ProfileManager

        public ProfileManager​(java.io.File catalog)
        Create a new ProfileManager. In almost all cases, the use of getDefault() is preferred.
        Parameters:
        catalog - the list of know profiles as an XML file

    • Method Detail

      • getDefault

        @Nonnull
public static ProfileManager getDefault()
        Get the default ProfileManager.

        The default ProfileManager needs to be loaded before the InstanceManager since user interaction with the ProfileManager may change how the InstanceManager is configured.

        Returns:
        the default ProfileManager.
        Since:
        3.11.8

      • getActiveProfile

        @CheckForNull
public Profile getActiveProfile()
        Get the Profile that is currently in use.

        Note that this returning null is not an error condition, and should not be treated as such, since there are times when the user interacts with a JMRI application that there should be no active profile.

        Returns:
        the in use Profile or null if there is no Profile in use

      • getActiveProfileName

        @CheckForNull
public java.lang.String getActiveProfileName()
        Get the name of the Profile that is currently in use.

        This is a convenience method that avoids a need to check that getActiveProfile() does not return null when all that is needed is the name of the active profile.

        Returns:
        the name of the active profile or null if there is no active profile

      • saveActiveProfile

        public void saveActiveProfile()
                       throws java.io.IOException
        Save the active Profile and automatic start setting.
        Throws:
        java.io.IOException - if unable to save the profile

      • setProfiles

        public void setProfiles​(Profile profile,
                        int index)
        Set the enabled Profile at index.
        Parameters:
        profile - the Profile to set
        index - the index to set; any existing profile at index is removed

      • getSearchPaths

        @Nonnull
public java.io.File[] getSearchPaths()
        Get the paths that are searched for Profiles when presenting the user with a list of Profiles. Profiles that are discovered in these paths are automatically added to the catalog.
        Returns:
        Paths that may contain profiles

      • getSearchPaths

        @CheckForNull
public java.io.File getSearchPaths​(int index)
        Get the search path at index.
        Parameters:
        index - the index of the search path
        Returns:
        A path that may contain profiles

      • addSearchPath

        protected void addSearchPath​(@Nonnull
                             java.io.File path)
                      throws java.io.IOException
        Throws:
        java.io.IOException

      • removeSearchPath

        protected void removeSearchPath​(@Nonnull
                                java.io.File path)
                         throws java.io.IOException
        Throws:
        java.io.IOException

      • setDefaultSearchPath

        protected void setDefaultSearchPath​(@Nonnull
                                    java.io.File defaultSearchPath)
                             throws java.io.IOException
        Throws:
        java.io.IOException

      • getConfigFile

        @CheckForNull
public java.io.File getConfigFile()
        Get the file used to configure the ProfileManager.
        Returns:
        the appConfigFile

      • setConfigFile

        public void setConfigFile​(@Nonnull
                          java.io.File configFile)
        Set the file used to configure the ProfileManager. This is set on a per-application basis.
        Parameters:
        configFile - the appConfigFile to set

      • isAutoStartActiveProfile

        public boolean isAutoStartActiveProfile()
        Should the app automatically start with the active Profile without offering the user an opportunity to change the Profile?
        Returns:
        true if the app should start without user interaction

      • setAutoStartActiveProfile

        public void setAutoStartActiveProfile​(boolean autoStartActiveProfile)
        Set if the app will next start without offering the user an opportunity to change the Profile.
        Parameters:
        autoStartActiveProfile - the autoStartActiveProfile to set

      • createDefaultProfile

        @CheckForNull
public Profile createDefaultProfile()
                             throws java.lang.IllegalArgumentException,
                                    java.io.IOException
        Create a default profile if no profiles exist.
        Returns:
        A new profile or null if profiles already exist
        Throws:
        java.lang.IllegalArgumentException - if profile already exists at default location
        java.io.IOException - if unable to create a Profile

      • migrateConfigToProfile

        @Nonnull
public Profile migrateConfigToProfile​(@Nonnull
                                      java.io.File config,
                                      @Nonnull
                                      java.lang.String name)
                               throws java.lang.IllegalArgumentException,
                                      java.io.IOException
        Copy a JMRI configuration not in a profile and its user preferences to a profile.
        Parameters:
        config - the configuration file
        name - the name of the configuration
        Returns:
        The profile with the migrated configuration
        Throws:
        java.io.IOException - if unable to create a Profile
        java.lang.IllegalArgumentException - if profile already exists for config

      • migrateToProfiles

        public boolean migrateToProfiles​(@Nonnull
                                 java.lang.String configFilename)
                          throws java.lang.IllegalArgumentException,
                                 java.io.IOException
        Migrate a JMRI application to using Profiles.

        Migration occurs when no profile configuration exists, but an application configuration exists. This method also handles the situation where an entirely new user is first starting JMRI, or where a user has deleted all their profiles.

        When a JMRI application is starting there are eight potential Profile-related states requiring preparation to use profiles:

        Matrix of states determining if migration required.
        Profile Catalog Profile Config App Config Action
        YES YES YES No preparation required - migration from earlier JMRI complete
        YES YES NO No preparation required - JMRI installed after profiles feature introduced
        YES NO YES Migration required - other JMRI applications migrated to profiles by this user, but not this one
        YES NO NO No preparation required - prompt user for desired profile if multiple profiles exist, use default otherwise
        NO NO NO New user - create and use default profile
        NO NO YES Migration required - need to create first profile
        NO YES YES No preparation required - catalog will be automatically regenerated
        NO YES NO No preparation required - catalog will be automatically regenerated
        This method returns true if a migration occurred, and false in all other circumstances.
        Parameters:
        configFilename - the name of the app config file
        Returns:
        true if a user's existing config was migrated, false otherwise
        Throws:
        java.io.IOException - if unable to to create a Profile
        java.lang.IllegalArgumentException - if profile already exists for configFilename

      • export

        public void export​(@Nonnull
                   Profile profile,
                   @Nonnull
                   java.io.File target,
                   boolean exportExternalUserFiles,
                   boolean exportExternalRoster)
            throws java.io.IOException,
                   JDOMException,
                   InitializationException
        Export the Profile to a zip file.
        Parameters:
        profile - The profile to export
        target - The file to export the profile into
        exportExternalUserFiles - If the User Files are not within the profile directory, should they be included?
        exportExternalRoster - It the roster is not within the profile directory, should it be included?
        Throws:
        java.io.IOException - if unable to write a file during the export
        JDOMException - if unable to create a new profile configuration file in the exported Profile
        InitializationException - if unable to read profile to export

      • createUniqueId

        @Nonnull
public static java.lang.String createUniqueId()
        Generate a reasonably pseudorandom unique id.

        This can be used to generate the id for a NullProfile. Implementing applications should save this value so that the id of a NullProfile is consistent across application launches.

        Returns:
        String of alphanumeric characters.

      • getAutoStartActiveProfileTimeout

        public int getAutoStartActiveProfileTimeout()
        Seconds to display profile selector before automatically starting.

        If 0, selector will not automatically dismiss.

        Returns:
        Seconds to display selector.

      • setAutoStartActiveProfileTimeout

        public void setAutoStartActiveProfileTimeout​(int autoStartActiveProfileTimeout)
        Set the number of seconds to display the profile selector before automatically starting.

        If negative or greater than 300 (5 minutes), set to 0 to prevent automatically starting with any profile.

        Call saveActiveProfile() after setting this to persist the value across application restarts.

        Parameters:
        autoStartActiveProfileTimeout - Seconds to display profile selector