Package com.inet.config

Class ConfigurationManager

java.lang.Object
com.inet.config.ConfigurationManager
public abstract class ConfigurationManager extends 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.

It is recommended to use the user scope if possible in order to avoid security problems.
Since:
inetcore 1.0
See Also:

  • Field Details

    • NAME_DEFAULT

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

    • COMMAND_LINE_CONFIG_PROPERTY

      public static final String COMMAND_LINE_CONFIG_PROPERTY
      -Dclearreports.config=USER/myConfig
      See Also:

    • ISINIT

      public static boolean ISINIT

  • Constructor Details

    • ConfigurationManager

      public ConfigurationManager()

  • Method Details

    • 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, 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 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:
      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 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 ('/') 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:
      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

      public abstract void delete(Configuration config) throws 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:
      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, String name) throws 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:
      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 export
      srcScope - scope of the configuration to export
      out - the output stream on which to emit the configuration's properties
      Throws:
      SecurityException - if you do not have permission to read from the scope specified
      IOException - if writing to the specified output stream results in an IOException
      Since:
      inetcore 1.0
      See Also:

    • get

      @Nullable public Configuration get(String fullName) throws 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:
      SecurityException - if it is not possible to read from the scope's root because of security reasons
      IllegalArgumentException - if the name is in the wrong format
      Since:
      inetcore 2.2

    • get

      @Nullable public abstract 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 fetch
      name - 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

      public abstract Configuration[] getAll(int scope)
      Returns all configurations in the given scope. The possible scopes are
      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:
      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

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

    • 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 specified
      IOException - If reading from the specified input stream results in an IOException
      Since:
      inetcore 1.0
      See Also:

    • put

      public abstract void put(int scope, String name, Configuration source) throws 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:
      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 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:
      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

      public abstract 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.
      Parameters:
      props - properties to pass the new configuration
      Returns:
      created temporary configuration
      Since:
      inetcore 1.0
      See Also:

    • setTemporaryPropertiesFromURL

      public abstract Configuration setTemporaryPropertiesFromURL(URL propsURL) throws 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:
      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 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:
      IllegalArgumentException - if scope if not Configuration.SCOPE_SYSTEM, Configuration.SCOPE_USER or Configuration.SCOPE_TEMP.
      Since:
      inetcore 1.0

    • getScopeName

      public static String getScopeName(int scope)
      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

      public abstract void addConfigurationChangeListener(ConfigurationChangeListener listener)
      Adds a listener for a ConfigurationChangeEvent. This event is fired, if:
      Parameters:
      listener - ConfigurationChangeListener, may not be null
      Throws:
      IllegalArgumentException - if listener is null
      Since:
      inetcore 1.0
      See Also:

    • removeConfigurationChangeListener

      public abstract void removeConfigurationChangeListener(ConfigurationChangeListener listener)
      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

      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

    • 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

      @Nullable public static String getRecoveryConfiguration()
      The preferred configuration of the recovery mode.
      Returns:
      the preferred configuration if set in the command line
      Since:
      inetcore 2.0

    • setRecoveryConfiguration

      public static void setRecoveryConfiguration(String configuration)
      FOR INTERNAL USE ONLY
      Parameters:
      configuration - the configuration
      Since:
      inetcore 2.0