com.inet.report.config
Class ConfigurationManager

java.lang.Object
  com.inet.report.config.ConfigurationManager

public 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 i-net Clear Reports to determine various behaviors, paths, and options. A description of each property and its possible values can be found here.

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:

8.0

See Also:

Preferences, Configuration

Field Summary

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.

Method Summary

void	addConfigurationChangeListener(ConfigurationChangeListener listener) Adds a listener for a ConfigurationChangeEvent.
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.
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.
protected com.inet.report.config.PreferencesAccessor	createPreferencesAccessor(java.util.prefs.Preferences prefs) creates an accessor for being able to put and retrieve long values
void	delete(Configuration config) Irreversible removes the specified configuration from storage.
void	delete(int scope, java.lang.String name) Irreversible removes the specified configuration from storage.
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(int scope, java.lang.String name) Fetches the configuration specified by the name and the scope.
Configuration[]	getAll(int scope) Returns all configurations in the given scope.
java.net.InetAddress[]	getAvailableIPAddresses() Returns all available IP addresses on the current system as a InetAddress array, each IP address as an individual InetAddress.
Configuration	getCurrent() Returns the current Configuration.
static ConfigurationManager	getInstance() Returns the singleton instance of the ConfigurationManager.
LicenseKeyInfo	getLicenseKeyInfo(java.lang.String licenseKey) Blocks for 2 seconds, then returns an object holding information about the license key given.
static java.lang.String	getScopeName(int scope) For debug purposes: returns the name of the given scope: "System", "User", or "Temp".
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	isReadable(int scope) Checks if the scope is readable by the current user.
static boolean	isWriteable(int scope) Checks if the scope is writeable by the current user.
void	put(int scope, java.lang.String name, Configuration source) Stores the configuration at the position specified.
void	removeConfigurationChangeListener(ConfigurationChangeListener listener) Removes a ConfigurationChangeListener.
void	rename(int srcScope, java.lang.String srcName, int destScope, java.lang.String destName) Renames and/or moves a configuration.
void	setCurrent(Configuration config) Sets the given configuration as the one currently being used by i-net Clear Reports instead of the default configuration as specified in getCurrent().
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.

Field Detail

NAME_DEFAULT

public static final 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.

See Also:

Constant Field Values

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

Method Detail

getInstance

public static ConfigurationManager getInstance()

Returns the singleton instance of the ConfigurationManager.

Returns:

Singleton instance of the ConfigurationManager

copy

public 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.

Since:

8.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

create

public 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.

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.

Since:

8.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

delete

public 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:

8.0

delete

public 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:

8.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

exportToStream

public 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:

8.0

See Also:

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

get

public 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:

8.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

getAll

public 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:

8.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

getAvailableIPAddresses

public 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:

8.0

setCurrent

public void setCurrent(Configuration config)

Sets the given configuration as the one currently being used by i-net Clear Reports 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.

getCurrent

public 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:

8.0

See Also:

Configuration.SCOPE_TEMP

importFromStream

public 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:

8.0

See Also:

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

getLicenseKeyInfo

public LicenseKeyInfo getLicenseKeyInfo(java.lang.String licenseKey)

Blocks for 2 seconds, then returns an object holding information about the license key given.

Parameters:

licenseKey - License Key to check

Returns:

LicenseKeyInfo with information about the license key provided

See Also:

LicenseKeyInfo

put

public 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:

8.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

rename

public 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:

8.0

See Also:

Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER, Configuration.SCOPE_TEMP

setTemporaryProperties

public 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

See Also:

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

createPreferencesAccessor

protected com.inet.report.config.PreferencesAccessor createPreferencesAccessor(java.util.prefs.Preferences prefs)

creates an accessor for being able to put and retrieve long values

Parameters:

prefs - underlying prefs

Returns:

accessor for putting and retrieving long values

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.

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:

8.0

getScopeName

public static java.lang.String getScopeName(int scope)

For debug purposes: returns the name of the given scope: "System", "User", or "Temp".

Parameters:

scope - scope to return name for

Returns:

prettified name of scope

addConfigurationChangeListener

public 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 i-net Clear Reports has changed. (see getCurrent())

Parameters:

listener - ConfigurationChangeListener, may not be null

Throws:

java.lang.IllegalArgumentException - if listener is null

See Also:

ConfigurationChangeListener, ConfigurationChangeEvent

removeConfigurationChangeListener

public void removeConfigurationChangeListener(ConfigurationChangeListener listener)

Removes a ConfigurationChangeListener.

Parameters:

listener - listener to remove, may not be null

Throws:

java.lang.IllegalArgumentException - if listener is null