com.inet.config

Class ConfigurationManager

java.lang.Object

com.inet.config.ConfigurationManager

public abstract class ConfigurationManager
extends java.lang.Object

Manager in charge of storing, creating, copying, renaming, deleting, and fetching configurations. A configuration is a storage of the various preferences used by the application to determine various behaviors, paths, and options. A description of each property and its possible values can be found in the help of the configuration manager web interface.

Configurations belong to one of three different, separate "scopes", which determine which preferences to use as the backing store for the configuration properties.

• Configuration.SCOPE_SYSTEM means the configuration is stored in the system preferences.
• Configuration.SCOPE_USER means the configuration is stored in the user preferences.
• Configuration.SCOPE_TEMP means the configuration is not stored permanently at all, but only used for the current session.

It is recommended to use the user scope if possible in order to avoid security problems.

Since:

inetcore 1.0

See Also:

Preferences, Configuration

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COMMAND_LINE_CONFIG_PROPERTY -Dclearreports.config=USER/myConfig
static boolean	ISINIT
static java.lang.String	NAME_DEFAULT The name to use for USER or SYSTEM configurations which are to be used by default.
static java.lang.String	NAME_TEMP_DEFAULT The name to use for TEMP configurations which are to be used by default.

Constructor Summary

Constructors

Constructor and Description
ConfigurationManager()

Method Summary

Modifier and Type	Method and Description
abstract void	addConfigurationChangeListener(ConfigurationChangeListener listener) Adds a listener for a ConfigurationChangeEvent.
abstract void	addConfigurationMigrator(ConfigurationMigrator migrator) Add a migrator for the configurations.
abstract void	copy(int srcScope, java.lang.String srcName, int destScope, java.lang.String destName) Creates a copy of the specified source configuration at the specified destination with the given name.
abstract Configuration	create(int scope, java.lang.String name) Creates a new, empty configuration with the given name and context and stores it in the appropriate Preferences.
abstract void	delete(Configuration config) Irreversible removes the specified configuration from storage.
abstract void	delete(int scope, java.lang.String name) Irreversible removes the specified configuration from storage.
abstract void	exportToStream(int srcScope, java.lang.String srcName, java.io.OutputStream out) Writes the properties in the configuration specified to the output stream in a format suitable for loading it back using the importFromStream method.
Configuration	get(java.lang.String fullName) Fetches the configuration specified by the name and the scope.
abstract Configuration	get(int scope, java.lang.String name) Fetches the configuration specified by the name and the scope.
abstract Configuration[]	getAll(int scope) Returns all configurations in the given scope.
abstract java.net.InetAddress[]	getAvailableIPAddresses() Returns all available IP addresses on the current system as a InetAddress array, each IP address as an individual InetAddress.
abstract Configuration	getCurrent() Returns the current Configuration.
static ConfigurationManager	getInstance() Returns the singleton instance of the ConfigurationManager.
static java.lang.String	getRecoveryConfiguration() The preferred configuration of the recovery mode.
abstract void	importFromStream(int destScope, java.lang.String destName, java.io.InputStream in) Imports all of the preferences represented by the properties stored in the stream.
static boolean	isHelpCenterMode() If the application run in help center mode.
static boolean	isReadable(int scope) Checks if the scope is readable by the current user.
static boolean	isRecoveryMode() If the application run in recovery mode.
static boolean	isWriteable(int scope) Checks if the scope is writeable by the current user.
abstract void	put(int scope, java.lang.String name, Configuration source) Stores the configuration at the position specified.
abstract void	removeConfigurationChangeListener(ConfigurationChangeListener listener) Removes the given ConfigurationChangeListener.
abstract void	removeConfigurationMigrator(ConfigurationMigrator migrator) Remove the given migrator from the list.
abstract void	rename(int srcScope, java.lang.String srcName, int destScope, java.lang.String destName) Renames and/or moves a configuration.
abstract void	setCurrent(Configuration config) Sets the given configuration as the one currently being used by the application instead of the default configuration as specified in getCurrent().
abstract Configuration	setTemporaryProperties(java.util.Properties props) Creates and returns a new temporary configuration called "<temp copy>", imports the given properties and sets the created configuration as the current configuration.
abstract Configuration	setTemporaryPropertiesFromURL(java.net.URL propsURL) Creates and returns a new temporary configuration called "<temp copy>", imports the given properties and sets the created configuration as the current configuration.

Field Detail

NAME_DEFAULT

public static java.lang.String NAME_DEFAULT

The name to use for USER or SYSTEM configurations which are to be used by default. See getCurrent() for more information on the order of where the default configuration is searched for.

NAME_TEMP_DEFAULT

public static final java.lang.String NAME_TEMP_DEFAULT

The name to use for TEMP configurations which are to be used by default. See getCurrent() for more information on the order of where the default configuration is searched for.

See Also:

Constant Field Values

COMMAND_LINE_CONFIG_PROPERTY

public static final java.lang.String COMMAND_LINE_CONFIG_PROPERTY

-Dclearreports.config=USER/myConfig

See Also:

Constant Field Values

ISINIT

public static boolean ISINIT

Constructor Detail

ConfigurationManager

public ConfigurationManager()

Method Detail

getInstance

public static ConfigurationManager getInstance()

Returns the singleton instance of the ConfigurationManager.

Returns:

Singleton instance of the ConfigurationManager

Since:

inetcore 1.0

copy

public abstract void copy(int srcScope,
                          java.lang.String srcName,
                          int destScope,
                          java.lang.String destName)
                   throws java.lang.SecurityException

Creates a copy of the specified source configuration at the specified destination with the given name. All properties of the original configuration are included in the new configuration as well.

Parameters:

srcName - name of configuration to copy

srcScope - scope of configuration to copy

destName - name of new, copied configuration. The name must be unique for the given scope.

destScope - scope to store the new, copied configuration in - SCOPE_SYSTEM, SCOPE_USER, SCOPE_TEMP

Throws:

java.lang.SecurityException - if you do not have permission to create a new configuration in the scope specified or if you do not have permission to read from the source configuration.

java.lang.IllegalArgumentException - if there is no configuration at the given source or destination

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

create

@Nonnull
public abstract Configuration create(int scope,
                                               java.lang.String name)
                                        throws java.lang.SecurityException

Creates a new, empty configuration with the given name and context and stores it in the appropriate Preferences. Using this empty configuration will cause all properties to have their default values.

Parameters:

name - name the new configuration should have. This name must be unique for the given scope and may not be null, empty, or contain a slash ('/') character

scope - scope to store the new configuration in - SCOPE_SYSTEM, SCOPE_USER, or SCOPE_TEMP

Returns:

new, empty configuration created and stored at the position specified

Throws:

java.lang.SecurityException - if you do not have permission to store a configuration in the scope specified.

java.lang.IllegalArgumentException - if the given name already exists as a configuration or if it is null, empty, or contains a slash character

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

delete

public abstract void delete(Configuration config)
                     throws java.lang.SecurityException

Irreversible removes the specified configuration from storage. Note that this Configuration as well as any other Configuration objects pointing to its location will no longer work because the Preferences node the Configuration points to will have been removed. If the current configuration (getCurrent() is being removed, this will additionally call setCurrent(null).

Parameters:

config - Configuration to remove from storage

Throws:

java.lang.SecurityException - if you do not have permission to remove the configuration from storage, i.e. if the configuration is in a scope for which you do not have write permission.

Since:

inetcore 1.0

delete

public abstract void delete(int scope,
                            java.lang.String name)
                     throws java.lang.SecurityException

Irreversible removes the specified configuration from storage. Note that any Configuration objects pointing to this location will no longer work after calling this method, since the Preferences node will have been deleted. If the current configuration (getCurrent() is being removed, this will additionally call setCurrent(null).

Parameters:

name - name of the configuration to delete

scope - scope of the configuration to delete, scope has to be exactly one of the defined scopes

Throws:

java.lang.SecurityException - if you do not have permission to delete the configuration in the scope specified.

java.lang.IllegalArgumentException - if you try to delete a non-existent configuration

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

exportToStream

public abstract void exportToStream(int srcScope,
                                    java.lang.String srcName,
                                    java.io.OutputStream out)
                             throws java.lang.SecurityException,
                                    java.io.IOException

Writes the properties in the configuration specified to the output stream in a format suitable for loading it back using the importFromStream method. The stream is written using the ISO 8859-1 character encoding.

After the stream is written to, it is flushed, but remains open after this method returns.

Parameters:

srcName - name of the configuration to export

srcScope - scope of the configuration to export

out - the output stream on which to emit the configuration's properties

Throws:

java.lang.SecurityException - if you do not have permission to read from the scope specified

java.io.IOException - if writing to the specified output stream results in an IOException

Since:

inetcore 1.0

See Also:

Properties.store(OutputStream, String), Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

get

@Nullable
public Configuration get(java.lang.String fullName)
                             throws java.lang.SecurityException

Fetches the configuration specified by the name and the scope. Will return null if no such configuration exists.

Parameters:

fullName - the configuration name in the format scope/name

Returns:

Configuration specified, or null if configuration could not be found

Throws:

java.lang.SecurityException - if it is not possible to read from the scope's root because of security reasons

java.lang.IllegalArgumentException - if the name is in the wrong format

Since:

inetcore 2.2

get

@Nullable
public abstract Configuration get(int scope,
                                             java.lang.String name)
                                      throws java.lang.SecurityException

Fetches the configuration specified by the name and the scope. Will return null if no such configuration exists.

Parameters:

scope - scope of configuration to fetch

name - name of configuration to fetch

Returns:

Configuration specified, or null if configuration could not be found

Throws:

java.lang.SecurityException - if it is not possible to read from the scope's root because of security reasons

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

getAll

public abstract Configuration[] getAll(int scope)

Returns all configurations in the given scope. The possible scopes are

• Configuration.SCOPE_SYSTEM - The system preferences
• Configuration.SCOPE_USER - The user preferences
• Configuration.SCOPE_TEMP - Preferences held temporarily without a backing store

If you'd like to fetch configurations from more than one scope, you can connect the scopes with a bit-wise OR operation.

 SCOPE_SYSTEM | SCOPE_USER
 

would fetch all configurations in the system and user preferences, for example.

Parameters:

scope - Scope to fetch the configurations from

Returns:

Array of all configurations in the given scope. Could be an empty array if no configurations are to be found in the specified scope

Throws:

java.lang.IllegalArgumentException - if you provide a scope which is neither one of the scopes nor put together by a bit-wise "OR" operation of more than one scope.

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

getAvailableIPAddresses

public abstract java.net.InetAddress[] getAvailableIPAddresses()

Returns all available IP addresses on the current system as a InetAddress array, each IP address as an individual InetAddress. Returns an empty InetAddress array if there are no IP addresses available or an error occur. The list include only IPv4 address without the loopback address.

Returns:

All available IP addresses on the current system, never NULL

Since:

inetcore 1.0

setCurrent

public abstract void setCurrent(Configuration config)

Sets the given configuration as the one currently being used by the application instead of the default configuration as specified in getCurrent(). Note that you can set null here, this will cause the default configuration to be used instead. Note also that this setting is not persistent, in other words it applies only for this session.

Parameters:

config - Configuration to set as the "current" configuration for this session only.

Since:

inetcore 1.0

getCurrent

@Nonnull
public abstract Configuration getCurrent()

Returns the current Configuration. This method will never return null. The configuration is retrieved from the first location possible, in the following order:

1. If a configuration has been set via setCurrent(Configuration) for this session, this configuration is returned. If it has changed since the setCurrent call, a new instance is created with refreshed content.
2. The configuration at the location specified in the environment variable "ClearReports.config"
3. The properties in the property file at the location provided in the environment variable "ClearReports.configfile" - these properties are imported into a temporary configuration called "<imported configuration>".
4. The node "Default" in the user preferences
5. The node "Default" in the system preferences

If no configuration can be found at any of these locations, this method will return a new, empty configuration with a scope of SCOPE_TEMP, meaning the configuration will not be stored permanently.

Returns:

Configuration currently used by this runtime.

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_TEMP

importFromStream

public abstract void importFromStream(int destScope,
                                      java.lang.String destName,
                                      java.io.InputStream in)
                               throws java.lang.SecurityException,
                                      java.io.IOException

Imports all of the preferences represented by the properties stored in the stream. This method is designed for use with the exportToStream method.

If a configuration specified by the name and scope already exists, properties will be replaced by the properties in the stream if they exist there. If a configuration does not exist, one will be created at the position given.

Parameters:

destName - name of the configuration to import the preferences into. If no such configuration exists, one will be created.

destScope - sScope of the configuration to import the preferences into.

in - the input stream from which to read the properties

Throws:

java.lang.SecurityException - if you do not have permission to write to the configuration specified

java.io.IOException - If reading from the specified input stream results in an IOException

Since:

inetcore 1.0

See Also:

Properties.load(InputStream), exportToStream(int, String, OutputStream), Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

put

public abstract void put(int scope,
                         java.lang.String name,
                         Configuration source)
                  throws java.lang.SecurityException

Stores the configuration at the position specified. If a configuration already exists there, the configuration will be deleted and replaced by the new configuration. The name must be unique for the given scope and may not be empty or null.

Parameters:

scope - scope the configuration is to be stored in

name - name the configuration is to have

source - Configuration to store - if null is set, this will be the equivalent to delete(int, String).

Throws:

java.lang.SecurityException - if you do not have permission to write to the given scope

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

rename

public abstract void rename(int srcScope,
                            java.lang.String srcName,
                            int destScope,
                            java.lang.String destName)
                     throws java.lang.SecurityException

Renames and/or moves a configuration. The new name given must be unique for the new scope given. This is equivalent to first calling copy(int, String, int, String) with the given parameters, and then calling delete(Configuration) on the old configuration. The new name does not need to be different from the old name, however it must not be empty nor null and must be unique for the scope given.

Parameters:

srcScope - Scope of the configuration to rename or move

srcName - Name of the configuration to rename or move

destScope - New scope to give the configuration

destName - New name to give the configuration

Throws:

java.lang.SecurityException - if you do not have permission to read, write, or delete a configuration in its given scope.

Since:

inetcore 1.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

setTemporaryProperties

public abstract Configuration setTemporaryProperties(java.util.Properties props)

Creates and returns a new temporary configuration called "<temp copy>", imports the given properties and sets the created configuration as the current configuration.

Parameters:

props - properties to pass the new configuration

Returns:

created temporary configuration

Since:

inetcore 1.0

See Also:

create(int, String), Configuration.putAll(java.util.Map), setCurrent(Configuration)

setTemporaryPropertiesFromURL

public abstract Configuration setTemporaryPropertiesFromURL(java.net.URL propsURL)
                                                     throws java.io.IOException

Creates and returns a new temporary configuration called "<temp copy>", imports the given properties and sets the created configuration as the current configuration.

Parameters:

propsURL - URL to a property file

Returns:

created temporary configuration

Throws:

java.io.IOException - if any I/O Error occur

Since:

inetcore 3.2

See Also:

create(int, String), Configuration.putAll(java.util.Map), setCurrent(Configuration)

isReadable

public static boolean isReadable(int scope)

Checks if the scope is readable by the current user. The temporary scope is always readable. To test readability, a list of the nodes in the scope is attempted to be fetched. If a BackingStoreException or SecurityException occurs, the scope is not readable and false is returned.

Parameters:

scope - Possible values:

• Configuration.SCOPE_SYSTEM
• Configuration.SCOPE_USER
• Configuration.SCOPE_TEMP

Returns:

true if the scope is readable, false otherwise.

Throws:

java.lang.IllegalArgumentException - if scope if not Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER or Configuration.SCOPE_TEMP.

Since:

inetcore 1.0

isWriteable

public static boolean isWriteable(int scope)

Checks if the scope is writeable by the current user. The temporary scope is always writeable. A dummy node is created and then removed to test the permissions. If a BackingStoreException or SecurityException occurs, the scope is not writeable, and false is returned.

Parameters:

scope - Possible values:

• Configuration.SCOPE_SYSTEM
• Configuration.SCOPE_USER
• Configuration.SCOPE_TEMP

Returns:

true if the scope is writable.

Throws:

java.lang.IllegalArgumentException - if scope if not Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER or Configuration.SCOPE_TEMP.

Since:

inetcore 1.0

addConfigurationChangeListener

public abstract void addConfigurationChangeListener(ConfigurationChangeListener listener)

Adds a listener for a ConfigurationChangeEvent. This event is fired, if:

• A Configuration has changed through Configuration.put(String, String) or Configuration.putAll(java.util.Map).
• The "current" configuration used by the application has changed. (see getCurrent())

Parameters:

listener - ConfigurationChangeListener, may not be null

Throws:

java.lang.IllegalArgumentException - if listener is null

Since:

inetcore 1.0

See Also:

ConfigurationChangeListener, ConfigurationChangeEvent

removeConfigurationChangeListener

public abstract void removeConfigurationChangeListener(ConfigurationChangeListener listener)

Removes the given ConfigurationChangeListener.

Parameters:

listener - listener to remove, may not be null

Throws:

java.lang.IllegalArgumentException - if null is passed in

Since:

inetcore 1.0

addConfigurationMigrator

public abstract void addConfigurationMigrator(ConfigurationMigrator migrator)

Add a migrator for the configurations. One configuration will migrate only only once.

Parameters:

migrator - the migrator

Since:

inetcore 1.0

removeConfigurationMigrator

public abstract void removeConfigurationMigrator(ConfigurationMigrator migrator)

Remove the given migrator from the list.

Parameters:

migrator - the migrator to remove.

Since:

inetcore 1.0

isRecoveryMode

public static boolean isRecoveryMode()

If the application run in recovery mode.

Returns:

true, if the recovery mode was started

Since:

inetcore 2.0

isHelpCenterMode

public static boolean isHelpCenterMode()

If the application run in help center mode.

Returns:

true, if the help center mode was started

Since:

inetcore 3.0

getRecoveryConfiguration

@Nullable
public static java.lang.String getRecoveryConfiguration()

The preferred configuration of the recovery mode.

Returns:

the preferred configuration if set in the command line

Since:

inetcore 2.0