Package jmri.profile

Class ProfileManager

java.lang.Object

jmri.beans.UnboundBean

jmri.beans.Bean

jmri.profile.ProfileManager

All Implemented Interfaces:

BeanInterface, PropertyChangeFirer, PropertyChangeProvider

public class ProfileManager
extends Bean

Manage JMRI configuration profiles.

This manager, and its configuration, fall outside the control of the ConfigureManager since the ConfigureManager's configuration is influenced by this manager.

Field Summary

Fields

Modifier and Type	Field	Description
static String	ACTIVE_PROFILE
static String	DEFAULT
static String	DEFAULT_SEARCH_PATH
static String	NEXT_PROFILE
static String	PROFILES
static String	SEARCH_PATHS
static String	SYSTEM_PROPERTY

Fields inherited from class jmri.beans.Bean

propertyChangeSupport

Constructor Summary

Constructors

Constructor	Description
ProfileManager()	Create a new ProfileManager using the default catalog.
ProfileManager(File catalog)	Create a new ProfileManager.

Method Summary

Modifier and Type	Method	Description
protected void	addProfile(Profile profile)
protected void	addSearchPath(File path)
Profile	createDefaultProfile()	Create a default profile if no profiles exist.
static String	createUniqueId()	Generate a reasonably pseudorandom unique id.
void	export(Profile profile, File target, boolean exportExternalUserFiles, boolean exportExternalRoster)	Export the Profile to a zip file.
Profile	getActiveProfile()	Get the Profile that is currently in use.
String	getActiveProfileName()	Get the name of the Profile that is currently in use.
List<Profile>	getAllProfiles()	Get an ArrayList of Profile objects.
ArrayList<File>	getAllSearchPaths()
int	getAutoStartActiveProfileTimeout()	Seconds to display profile selector before automatically starting.
File	getConfigFile()	Get the file used to configure the ProfileManager.
static ProfileManager	getDefault()	Get the default ProfileManager.
protected File	getDefaultSearchPath()
Profile	getNextActiveProfile()
Profile[]	getProfiles()	Get an array of enabled Profile objects.
Profile	getProfiles(int index)	Get the enabled Profile at index.
File[]	getSearchPaths()	Get the paths that are searched for Profiles when presenting the user with a list of Profiles.
File	getSearchPaths(int index)	Get the search path at index.
static Profile	getStartingProfile()	Get the active profile.
boolean	isAutoStartActiveProfile()	Should the app automatically start with the active Profile without offering the user an opportunity to change the Profile?
Profile	migrateConfigToProfile(File config, String name)	Copy a JMRI configuration not in a profile and its user preferences to a profile.
boolean	migrateToProfiles(String configFilename)	Migrate a JMRI application to using Profiles.
(package private) void	profileNameChange(Profile profile, String oldName)
void	readActiveProfile()	Read the active Profile and automatic start setting from the ProfileManager config file.
protected void	removeProfile(Profile profile)
protected void	removeSearchPath(File path)
void	saveActiveProfile()	Save the active Profile and automatic start setting.
protected void	saveActiveProfile(Profile profile, boolean autoStart)
void	setActiveProfile(String identifier)	Set the Profile to use.
void	setActiveProfile(Profile profile)	Set the Profile to use.
void	setAutoStartActiveProfile(boolean autoStartActiveProfile)	Set if the app will next start without offering the user an opportunity to change the Profile.
void	setAutoStartActiveProfileTimeout(int autoStartActiveProfileTimeout)	Set the number of seconds to display the profile selector before automatically starting.
void	setConfigFile(File configFile)	Set the file used to configure the ProfileManager.
protected void	setDefaultSearchPath(File defaultSearchPath)
protected void	setNextActiveProfile(Profile profile)
void	setProfiles(Profile profile, int index)	Set the enabled Profile at index.

Methods inherited from class jmri.beans.Bean

addPropertyChangeListener, addPropertyChangeListener, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeListeners, getPropertyChangeListeners, isNotifyOnEDT, removePropertyChangeListener, removePropertyChangeListener

Methods inherited from class jmri.beans.UnboundBean

getIndexedProperty, getProperty, getPropertyNames, hasIndexedProperty, hasProperty, setIndexedProperty, setProperty

Methods inherited from class java.lang.Object

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

Field Detail

ACTIVE_PROFILE

public static final String ACTIVE_PROFILE

See Also:

Constant Field Values

NEXT_PROFILE

public static final String NEXT_PROFILE

See Also:

Constant Field Values

PROFILES

public static final String PROFILES

See Also:

Constant Field Values

SEARCH_PATHS

public static final String SEARCH_PATHS

See Also:

Constant Field Values

DEFAULT

public static final String DEFAULT

See Also:

Constant Field Values

DEFAULT_SEARCH_PATH

public static final String DEFAULT_SEARCH_PATH

See Also:

Constant Field Values

SYSTEM_PROPERTY

public static final String SYSTEM_PROPERTY

See Also:

Constant Field Values

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(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 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

setActiveProfile

public void setActiveProfile(@CheckForNull
                             String identifier)

Set the Profile to use. This method finds the Profile by path or Id and calls setActiveProfile(jmri.profile.Profile).

Parameters:

identifier - the profile path or id; can be null

setActiveProfile

public void setActiveProfile(@CheckForNull
                             Profile profile)

Set the Profile to use.

Once the ConfigureManager is loaded, this only sets the Profile used at next application start.

Parameters:

profile - the profile to activate

getNextActiveProfile

@CheckForNull
public Profile getNextActiveProfile()

setNextActiveProfile

protected void setNextActiveProfile(@CheckForNull
                                    Profile profile)

saveActiveProfile

public void saveActiveProfile()
                       throws IOException

Save the active Profile and automatic start setting.

Throws:

IOException - if unable to save the profile

saveActiveProfile

protected void saveActiveProfile(@CheckForNull
                                 Profile profile,
                                 boolean autoStart)
                          throws IOException

Throws:

IOException

readActiveProfile

public void readActiveProfile()
                       throws IOException

Read the active Profile and automatic start setting from the ProfileManager config file.

Throws:

IOException - if unable to read the profile

See Also:

getConfigFile(), setConfigFile(java.io.File)

getProfiles

@Nonnull
public Profile[] getProfiles()

Get an array of enabled Profile objects.

Returns:

The enabled Profile objects

getAllProfiles

@Nonnull
public List<Profile> getAllProfiles()

Get an ArrayList of Profile objects.

Returns:

A list of all Profile objects

getProfiles

@CheckForNull
public Profile getProfiles(int index)

Get the enabled Profile at index.

Parameters:

index - the index of the desired Profile

Returns:

A 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

addProfile

protected void addProfile(Profile profile)

removeProfile

protected void removeProfile(Profile profile)

getSearchPaths

@Nonnull
public 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

getAllSearchPaths

public ArrayList<File> getAllSearchPaths()

getSearchPaths

@CheckForNull
public 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
                             File path)
                      throws IOException

Throws:

IOException

removeSearchPath

protected void removeSearchPath(@Nonnull
                                File path)
                         throws IOException

Throws:

IOException

getDefaultSearchPath

@Nonnull
protected File getDefaultSearchPath()

setDefaultSearchPath

protected void setDefaultSearchPath(@Nonnull
                                    File defaultSearchPath)
                             throws IOException

Throws:

IOException

getConfigFile

@CheckForNull
public File getConfigFile()

Get the file used to configure the ProfileManager.

Returns:

the appConfigFile

setConfigFile

public void setConfigFile(@Nonnull
                          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 IllegalArgumentException,
                                    IOException

Create a default profile if no profiles exist.

Returns:

A new profile or null if profiles already exist

Throws:

IllegalArgumentException - if profile already exists at default location

IOException - if unable to create a Profile

migrateConfigToProfile

@Nonnull
public Profile migrateConfigToProfile(@Nonnull
                                      File config,
                                      @Nonnull
                                      String name)
                               throws IllegalArgumentException,
                                      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:

IOException - if unable to create a Profile

IllegalArgumentException - if profile already exists for config

migrateToProfiles

public boolean migrateToProfiles(@Nonnull
                                 String configFilename)
                          throws IllegalArgumentException,
                                 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:

IOException - if unable to to create a Profile

IllegalArgumentException - if profile already exists for configFilename

export

public void export(@Nonnull
                   Profile profile,
                   @Nonnull
                   File target,
                   boolean exportExternalUserFiles,
                   boolean exportExternalRoster)
            throws 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:

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

getStartingProfile

@CheckForNull
public static Profile getStartingProfile()
                                  throws IOException

Get the active profile.

This method initiates the process of setting the active profile when a headless app launches.

Returns:

The active Profile

Throws:

IOException - if unable to read the current active profile

See Also:

ProfileManagerDialog.getStartingProfile(java.awt.Frame)

createUniqueId

@Nonnull
public static 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.

profileNameChange

void profileNameChange(Profile profile,
                       String oldName)

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