Package com.inet.config
Class ConfigurationManager
java.lang.Object
com.inet.config.ConfigurationManager
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.
- Since:
- inetcore 1.0
- See Also:
-
Field Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
Adds a listener for a ConfigurationChangeEvent.abstract void
Add a migrator for the configurations.abstract void
Creates a copy of the specified source configuration at the specified destination with the given name.abstract @Nonnull Configuration
Creates a new, empty configuration with the given name and context and stores it in the appropriate Preferences.abstract void
Irreversible removes the specified configuration from storage.abstract void
delete
(Configuration config) Irreversible removes the specified configuration from storage.abstract void
exportToStream
(int srcScope, String srcName, 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.abstract @Nullable Configuration
Fetches the configuration specified by the name and the scope.@Nullable Configuration
Fetches the configuration specified by the name and the scope.abstract Configuration[]
getAll
(int scope) Returns all configurations in the given scope.abstract InetAddress[]
Returns all available IP addresses on the current system as a InetAddress array, each IP address as an individual InetAddress.abstract @Nonnull Configuration
Returns the current Configuration.static ConfigurationManager
Returns the singleton instance of the ConfigurationManager.static @Nullable String
The preferred configuration of the recovery mode.static String
getScopeName
(int scope) FOR INTERNAL USE ONLY
Returns the name of the given scope: "System", "User", or "Temp".abstract void
importFromStream
(int destScope, String destName, InputStream in) Imports all of the preferences represented by the properties stored in the stream.static boolean
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
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, String name, Configuration source) Stores the configuration at the position specified.abstract void
Removes the given ConfigurationChangeListener.abstract void
Remove the given migrator from the list.abstract void
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 ingetCurrent()
.static void
setHelpCenterMode
(boolean mode) FOR INTERNAL USE ONLYstatic void
setRecoveryConfiguration
(String configuration) FOR INTERNAL USE ONLYstatic void
setRecoveryMode
(boolean mode) FOR INTERNAL USE ONLYabstract Configuration
setTemporaryProperties
(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
(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 Details
-
NAME_DEFAULT
The name to use for USER or SYSTEM configurations which are to be used by default. SeegetCurrent()
for more information on the order of where the default configuration is searched for. -
NAME_TEMP_DEFAULT
The name to use for TEMP configurations which are to be used by default. SeegetCurrent()
for more information on the order of where the default configuration is searched for.- See Also:
-
COMMAND_LINE_CONFIG_PROPERTY
-Dclearreports.config=USER/myConfig- See Also:
-
ISINIT
public static boolean ISINIT
-
-
Constructor Details
-
ConfigurationManager
public ConfigurationManager()
-
-
Method Details
-
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, String srcName, int destScope, String destName) throws 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 copysrcScope
- scope of configuration to copydestName
- 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:
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.IllegalArgumentException
- if there is no configuration at the given source or destination- Since:
- inetcore 1.0
- See Also:
-
create
@Nonnull public abstract @Nonnull Configuration create(int scope, String name) throws 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 ('/') characterscope
- 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:
SecurityException
- if you do not have permission to store a configuration in the scope specified.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:
-
delete
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 callsetCurrent(null)
.- Parameters:
config
- Configuration to remove from storage- Throws:
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
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 callsetCurrent(null)
.- Parameters:
name
- name of the configuration to deletescope
- scope of the configuration to delete, scope has to be exactly one of the defined scopes- Throws:
SecurityException
- if you do not have permission to delete the configuration in the scope specified.IllegalArgumentException
- if you try to delete a non-existent configuration- Since:
- inetcore 1.0
- See Also:
-
exportToStream
public abstract void exportToStream(int srcScope, String srcName, OutputStream out) throws SecurityException, 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 exportsrcScope
- scope of the configuration to exportout
- the output stream on which to emit the configuration's properties- Throws:
SecurityException
- if you do not have permission to read from the scope specifiedIOException
- if writing to the specified output stream results in an IOException- Since:
- inetcore 1.0
- See Also:
-
get
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:
SecurityException
- if it is not possible to read from the scope's root because of security reasonsIllegalArgumentException
- if the name is in the wrong format- Since:
- inetcore 2.2
-
get
@Nullable public abstract @Nullable Configuration get(int scope, String name) throws 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 fetchname
- name of configuration to fetch- Returns:
- Configuration specified, or null if configuration could not be found
- Throws:
SecurityException
- if it is not possible to read from the scope's root because of security reasons- Since:
- inetcore 1.0
- See Also:
-
getAll
Returns all configurations in the given scope. The possible scopes are
Configuration.SCOPE_SYSTEM
- The system preferencesConfiguration.SCOPE_USER
- The user preferencesConfiguration.SCOPE_TEMP
- Preferences held temporarily without a backing store
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:
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:
-
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
Sets the given configuration as the one currently being used by the application instead of the default configuration as specified ingetCurrent()
. 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
Returns the current Configuration. This method will never return null. The configuration is retrieved from the first location possible, in the following order:- 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. - The configuration at the location specified in the environment variable "ClearReports.config"
- 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>".
- The node "Default" in the user preferences
- The node "Default" in the system preferences
- Returns:
- Configuration currently used by this runtime.
- Since:
- inetcore 1.0
- See Also:
- If a configuration has been set via
-
importFromStream
public abstract void importFromStream(int destScope, String destName, InputStream in) throws SecurityException, 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:
SecurityException
- if you do not have permission to write to the configuration specifiedIOException
- If reading from the specified input stream results in an IOException- Since:
- inetcore 1.0
- See Also:
-
put
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 inname
- name the configuration is to havesource
- Configuration to store - if null is set, this will be the equivalent todelete(int, String)
.- Throws:
SecurityException
- if you do not have permission to write to the given scope- Since:
- inetcore 1.0
- See Also:
-
rename
public abstract void rename(int srcScope, String srcName, int destScope, String destName) throws SecurityException Renames and/or moves a configuration. The new name given must be unique for the new scope given. This is equivalent to first callingcopy(int, String, int, String)
with the given parameters, and then callingdelete(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 movesrcName
- Name of the configuration to rename or movedestScope
- New scope to give the configurationdestName
- New name to give the configuration- Throws:
SecurityException
- if you do not have permission to read, write, or delete a configuration in its given scope.- Since:
- inetcore 1.0
- See Also:
-
setTemporaryProperties
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:
-
setTemporaryPropertiesFromURL
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:
IOException
- if any I/O Error occur- Since:
- inetcore 3.2
- See Also:
-
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:
IllegalArgumentException
- if scope if notConfiguration.SCOPE_SYSTEM
,Configuration.SCOPE_USER
orConfiguration.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:
IllegalArgumentException
- if scope if notConfiguration.SCOPE_SYSTEM
,Configuration.SCOPE_USER
orConfiguration.SCOPE_TEMP
.- Since:
- inetcore 1.0
-
getScopeName
FOR INTERNAL USE ONLY
Returns the name of the given scope: "System", "User", or "Temp".- Parameters:
scope
- scope to return name for- Returns:
- prettified name of scope
-
addConfigurationChangeListener
Adds a listener for a ConfigurationChangeEvent. This event is fired, if:- A
Configuration
has changed throughConfiguration.put(String, String)
orConfiguration.putAll(java.util.Map)
. - The "current" configuration used by the application has changed. (see
getCurrent()
)
- Parameters:
listener
- ConfigurationChangeListener, may not be null- Throws:
IllegalArgumentException
- if listener is null- Since:
- inetcore 1.0
- See Also:
- A
-
removeConfigurationChangeListener
Removes the given ConfigurationChangeListener.- Parameters:
listener
- listener to remove, may not be null- Throws:
IllegalArgumentException
- if null is passed in- Since:
- inetcore 1.0
-
addConfigurationMigrator
Add a migrator for the configurations. One configuration will migrate only only once.- Parameters:
migrator
- the migrator- Since:
- inetcore 1.0
-
removeConfigurationMigrator
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
-
setRecoveryMode
public static void setRecoveryMode(boolean mode) FOR INTERNAL USE ONLY- Parameters:
mode
- the mode.- 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
-
setHelpCenterMode
public static void setHelpCenterMode(boolean mode) FOR INTERNAL USE ONLY- Parameters:
mode
- the mode.- Since:
- inetcore 3.0
-
getRecoveryConfiguration
The preferred configuration of the recovery mode.- Returns:
- the preferred configuration if set in the command line
- Since:
- inetcore 2.0
-
setRecoveryConfiguration
FOR INTERNAL USE ONLY- Parameters:
configuration
- the configuration- Since:
- inetcore 2.0
-