Package com.inet.config

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

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

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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​(int scope, java.lang.String name)
      Irreversible removes the specified configuration from storage.
      abstract void delete​(Configuration config)
      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.
      abstract Configuration get​(int scope, java.lang.String name)
      Fetches the configuration specified by the name and the scope.
      Configuration get​(java.lang.String fullName)
      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.
      static java.lang.String getScopeName​(int scope)
      FOR INTERNAL USE ONLY
      Returns the name of the given scope: "System", "User", or "Temp".
      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().
      static void setHelpCenterMode​(boolean mode)
      FOR INTERNAL USE ONLY
      static void setRecoveryConfiguration​(java.lang.String configuration)
      FOR INTERNAL USE ONLY
      static void setRecoveryMode​(boolean mode)
      FOR INTERNAL USE ONLY
      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.

      • Methods inherited from class java.lang.Object

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

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

      • getScopeName

        public static java.lang.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

      • 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

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

      • setRecoveryConfiguration

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