Package com.opencloud.rhino.logging

Interface LoggingManagementMBean

  • public interface LoggingManagementMBean

    The LoggingManagementMBean interface provides methods to modify Rhino’s log configuration.

    • Method Detail

      • setLogLevel

        @Deprecated
void setLogLevel​(String logKey,
                 String level)
          throws com.opencloud.util.exception.ValidationException,
                 ConfigurationException
        Deprecated.
        use setLoggerLevel(String, String) instead.

        Set the log filter level for a log key.

        Parameters:
        logKey - the log key of the logger, or "root" to update the root logger.
        level - the desired log level, or null to clear a previously set log level.
        Throws:
        com.opencloud.util.exception.ValidationException - if a validation error occurs updating the logger configuration.
        ConfigurationException - if a error occurred updating the logger configuration.

      • setLoggerLevel

        void setLoggerLevel​(String logKey,
                    String level)
             throws com.opencloud.util.exception.ValidationException,
                    ConfigurationException

        Set the log filter level for a log key.

        Parameters:
        logKey - the log key of the logger, or "root" to update the root logger.
        level - the desired log level, or null to clear a previously set log level.
        Throws:
        com.opencloud.util.exception.ValidationException - if a validation error occurs updating the logger configuration.
        ConfigurationException - if a error occurred updating the logger configuration.
        Since:
        Rhino 2.6.0

      • setAdditivity

        @Deprecated
void setAdditivity​(String logKey,
                   boolean additivity)
            throws com.opencloud.util.exception.ValidationException,
                   ConfigurationException
        Deprecated.
        use setLoggerAdditivity(String, Boolean) instead.

        Set the additivity for a log key.

        A logger with additivity enabled propagates log messages sent to it to its parent logger. A logger with additivity disabled suppresses this behaviour.

        The default behaviour for loggers is that additivity is enabled.

        Parameters:
        logKey - the log key of the logger.
        additivity - true for enabled or false for disabled.
        Throws:
        com.opencloud.util.exception.ValidationException - if a validation error occurs updating the logger configuration.
        ConfigurationException - if a error occurred updating the logger configuration.

      • setLoggerAdditivity

        void setLoggerAdditivity​(String logKey,
                         Boolean additivity)
                  throws com.opencloud.util.exception.ValidationException,
                         ConfigurationException

        Set the additivity for a log key.

        A logger with additivity enabled propagates log messages sent to it to its parent logger. A logger with additivity disabled suppresses this behaviour.

        The default behaviour for loggers is that additivity is enabled.

        Parameters:
        logKey - the log key of the logger.
        additivity - true for enabled, false for disabled, or null to use the platform default.
        Throws:
        com.opencloud.util.exception.ValidationException - if a validation error occurs updating the logger configuration.
        ConfigurationException - if a error occurred updating the logger configuration.
        Since:
        Rhino 2.6.0

      • setLoggerAsynchronous

        void setLoggerAsynchronous​(String logKey,
                           Boolean asynchronous)
                    throws com.opencloud.util.exception.ValidationException,
                           ConfigurationException

        Set the asynchronous mode for a log key.

        Parameters:
        logKey - the log key of the logger, or "root" to update the root logger.
        asynchronous - true for asynchronous, false for synchronous), or null to use the platform default.
        Throws:
        com.opencloud.util.exception.ValidationException - if a validation error occurs updating the logger configuration.
        ConfigurationException - if a error occurred updating the logger configuration.

      • addAppenderRef

        void addAppenderRef​(String logKey,
                    String appenderRef)
             throws UnknownAppenderException,
                    com.opencloud.util.exception.ValidationException,
                    ConfigurationException

        Add a log appender to a log key.

        Parameters:
        logKey - the log key of the logger, or "root" to update the root logger.
        appenderRef - the name of the appender.
        Throws:
        UnknownAppenderException - if the appender name is not recognised.
        com.opencloud.util.exception.ValidationException - if a validation error occurs updating the logger configuration.
        ConfigurationException - if a error occurred updating the logger configuration.

      • setThreshold

        void setThreshold​(String appenderName,
                  String threshold)
           throws com.opencloud.util.exception.ValidationException,
                  ConfigurationException

        Sets the log filter level for an appender. Log messages logged at a level below the threshold will not be output. Setting the threshold to null will unset any previously set appender threshold.

        Parameters:
        appenderName - the name of the appender to reference.
        threshold - the log level, or null to unset the threshold.
        Throws:
        com.opencloud.util.exception.ValidationException - if a validation error occurs updating the appender configuration.
        ConfigurationException - if a error occurred updating the appender configuration.

      • rolloverAllLogFiles

        void rolloverAllLogFiles()
                  throws ConfigurationException

        Roll over the log files for all file appenders. A backup of the each log file is created and then the log file truncated.

        Throws:
        ConfigurationException - if a error occurred rolling the appenders.

      • getLoggerConfig

        CompositeData getLoggerConfig​(String logKey)
                       throws NullPointerException,
                              LoggerNotConfiguredException,
                              ConfigurationException,
                              ManagementException

        Get a description of a log key’s configuration.

        The CompositeData object returned by this method has the following structure:

        Field Open Type Description

        name

        String

        The name (ie. log key) of the logging configuration.

        log-level

        String

        The log filter level assigned to the logger, if any.

        additivity

        Boolean

        Indicator of logger additivity, if configured.

        asynchronous

        Boolean

        Indicator of logger asynchronosity, if configured.

        appender-refs

        String[]

        The names of the appenders attached to the logger.

        plugin-refs

        String[]

        The names of the plugin components directly attached to the logger.

        plugins

        CompositeData[]

        [multiblock cell omitted]

        Each plugin description is expressed as a CompositeData object with the following structure:

        Field Open Type Description

        pluginName

        String

        The name of the plugin component.

        properties

        CompositeData[]

        Descriptions of configuration properties provided to the plugin component. The format of this composite data is given below.

        componentType

        CompositeData[]

        [multiblock cell omitted]

        Each plugin configuration property is expressed as a CompositeData object with the following structure:

        Field Open Type Description

        name

        String

        The name of the configuration property.

        value

        String

        The value given to the configuration property.
        Parameters:
        logKey - the log key of the logger.
        Returns:
        a CompositeData as given in the method description.
        Throws:
        NullPointerException - if logKey is null.
        LoggerNotConfiguredException - if a logger for the specified log key is not configured.
        ConfigurationException - if a error occurred reading the logger configuration.
        ManagementException - if the logger configuration could not be returned due to an internal error.
        Since:
        Rhino 2.6.0

      • getEffectiveLoggerConfig

        CompositeData getEffectiveLoggerConfig​(String logKey)
                                throws NullPointerException,
                                       ManagementException

        Get a description of a log key’s effective configuration.

        The CompositeData object returned by this method has the following structure:

        Field Open Type Description

        name

        String

        The name (ie. log key) of the logging configuration.

        log-level

        String

        The log level assigned to the logger, if any.

        additivity

        Boolean

        Indicator of logger additivity.

        asynchronous

        Boolean

        Indicator of logger asynchronosity.

        appender-refs

        String[]

        The names of the appenders attached to the logger.
        Parameters:
        logKey - the log key of the logger.
        Returns:
        a CompositeData as given in the method description.
        Throws:
        NullPointerException - if logKey is null.
        ManagementException - if the logger configuration could not be returned due to an internal error.

      • setLoggerConfig

        boolean setLoggerConfig​(String logKey,
                        String level,
                        Boolean additivity,
                        Boolean asynchronous,
                        String[] appenderRefs,
                        CompositeData[] components)
                 throws NullPointerException,
                        com.opencloud.util.exception.ValidationException,
                        ConfigurationException

        Create or update a log key’s configuration.

        If this method is used to update the configuration for log key that already has a configuration, it completely replaces that configuration with the arguments passed to this method. That is, it does not just update parameters where non-null values are passed in but completely empties out the existing configuration before applying the new parameters.

        Parameters:
        logKey - the log key of the logger.
        level - the log level to assign to the logger. May be null if no level should be assigned.
        additivity - the additivity of the logger. May be null if the default additivity should be used for the logger.
        asynchronous - the asynchronosity of the logger. May be null if the default asynchronosity should be used for the logger.
        appenderRefs - the names of the appenders that should be attached to the logger. May be null.
        components - descriptions of plugin components that should be associated with the logger. Appropriate CompositeData objects can be created using buildGenericComponent(java.lang.String, java.lang.String[], javax.management.openmbean.CompositeData[]). May be null.
        Returns:
        true if the logger configuration was successfully created, or false if the resulting configuration was equivalent to the default empty configuration and consequently deemed unnecessary and discarded. A discarded configuration means the log key will no longer appear as "configured".
        Throws:
        NullPointerException - if logKey is null.
        com.opencloud.util.exception.ValidationException - if the logger configuration fails a basic validation check.
        ConfigurationException - if an error occurs configuring the logger.
        Since:
        Rhino 2.6.0
        See Also:
        buildGenericComponent(String, String[], CompositeData[])

      • getAdditivity

        @Deprecated
boolean getAdditivity​(String logKey)
        Deprecated.
        use getLoggerAdditivity(String)} instead.

        Get the additivity of a log key.

        Parameters:
        logKey - the log key of the logger
        Returns:
        true if enabled or false if disabled. If the logger is not configured then the default platform additivity (true is returned.

      • getEffectiveLogLevel

        String getEffectiveLogLevel​(String logKey)

        Get the effective log level for a log key, whether or not it has been explicitly set. If the specified log key does not have its own level configured, this method returns the level used for the log key based on its ancestors.

        Parameters:
        logKey - the log key of the logger, or "root" to query the root logger
        Returns:
        the filter level used for the logger.

      • getLogLevel

        @Deprecated
String getLogLevel​(String logKey)
        Deprecated.
        use getLoggerLevel(String) instead.

        Get the filter log level for a log key. This does not take inherited levels into account and the return value may be null.

        Parameters:
        logKey - the log key of the logger.
        Returns:
        the log cut off filter level

      • getLogKeys

        String[] getLogKeys()

        Get a list of all known log keys. This does include the implicit log key "root".

        Returns:
        the log keys.

      • getConfiguredLogKeys

        String[] getConfiguredLogKeys()
                       throws ConfigurationException

        Get a list of all log keys that have some configuration associated with them.

        Returns:
        the log keys.
        Throws:
        ConfigurationException - if a error occurred reading the logger configuration.

      • isExists

        @Deprecated
boolean isExists​(String logKey)
        Deprecated.
        use isLoggerExists(String) instead.

        Determine if a logger for the given log key currently exists.

        Parameters:
        logKey - the log key of the logger
        Returns:
        true if a logger exists, false otherwise.

      • isLoggerExists

        boolean isLoggerExists​(String logKey)

        Determine if a logger for the given log key currently exists.

        Parameters:
        logKey - the log key of the logger
        Returns:
        true if a logger exists, false otherwise.
        Since:
        Rhino 2.6.0

      • getAppenderInfo

        CompositeData getAppenderInfo​(String appenderName)
                       throws UnknownAppenderException,
                              ConfigurationException

        Get a description of an appender configuration.

        The CompositeData object returned by this method has the following structure:

        Field Open Type Description

        pluginName

        String

        The name of the plugin component.

        properties

        CompositeData[]

        Descriptions of configuration properties provided to the plugin component. The format of this composite data is given below.

        componentType

        CompositeData[]

        [multiblock cell omitted]

        Each plugin configuration property is expressed as a CompositeData object with the following structure:

        Field Open Type Description

        name

        String

        The name of the configuration property.

        value

        String

        The value given to the configuration property.
        Parameters:
        appenderName - the name of the appender.
        Throws:
        UnknownAppenderException - if the appender name is not recognised.
        ConfigurationException - if a error occurred reading the appender configuration.
        Since:
        Rhino 2.6.0

      • getFileAppenderInfo

        @Deprecated
CompositeData getFileAppenderInfo​(String appenderName)
                           throws UnknownAppenderException,
                                  com.opencloud.util.exception.ValidationException,
                                  ConfigurationException
        Deprecated.
        use getAppenderInfo(String) instead.

        Get a description of a file appender’s configuration.

        The returned CompositeData contains three columns:

        • a java.lang.String column "filename"

        • a java.lang.String column "maximum-file-size"

        • a java.lang.Integer column "maximum-backup-files"

        Parameters:
        appenderName - the name of the appender.
        Throws:
        UnknownAppenderException - if the appender name is not recognised.
        com.opencloud.util.exception.ValidationException - if a validation error occurs, for example if the given appender isn’t of the correct type.
        ConfigurationException - if a error occurred reading the appender configuration.

      • getSocketAppenderInfo

        @Deprecated
CompositeData getSocketAppenderInfo​(String appenderName)
                             throws UnknownAppenderException,
                                    com.opencloud.util.exception.ValidationException,
                                    ConfigurationException
        Deprecated.
        use getAppenderInfo(String) instead.

        Get a description of a socket appender’s configuration.

        The returned CompositeData contains two columns:

        • a java.lang.String column "remote-host"

        • a java.lang.Integer column "port"

        Parameters:
        appenderName - the name of the appender.
        Throws:
        UnknownAppenderException - if the appender name is not recognised.
        com.opencloud.util.exception.ValidationException - if a validation error occurs, for example if the given appender isn’t of the correct type.
        ConfigurationException - if a error occurred reading the appender configuration.

      • getSyslogAppenderInfo

        @Deprecated
CompositeData getSyslogAppenderInfo​(String appenderName)
                             throws UnknownAppenderException,
                                    com.opencloud.util.exception.ValidationException,
                                    ConfigurationException
        Deprecated.
        use getAppenderInfo(String) instead.

        Get a description of a syslog appender’s configuration.

        The returned CompositeData contains two columns:

        • a java.lang.String columns "syslog-host"

        • a java.lang.String column "facility"

        Parameters:
        appenderName - the name of the appender.
        Throws:
        UnknownAppenderException - if the appender name is not recognised.
        com.opencloud.util.exception.ValidationException - if a validation error occurs, for example if the given appender isn’t of the correct type.
        ConfigurationException - if a error occurred reading the appender configuration.

      • getAppenderProperties

        TabularData getAppenderProperties​(String appenderName)
                           throws UnknownAppenderException,
                                  ConfigurationException

        Get the configuration properties for an appender.

        The returned TabularData contains a CompositeData row for each property. The CompositeData contains two columns:

        • a java.lang.String column "name"

        • a java.lang.String column "value"

        Parameters:
        appenderName - the name of the appender to reference
        Throws:
        UnknownAppenderException - if the appender name is not recognised.
        ConfigurationException - if a error occurred reading the appender configuration.

      • getThreshold

        String getThreshold​(String appenderName)
             throws UnknownAppenderException,
                    ConfigurationException

        Get the log filter level for and appender

        Log messages logged at a level below the threshold will not be output.

        Parameters:
        appenderName - the name of the appender.
        Returns:
        the log filter level, or null if a threshold is not configured for the appender.
        Throws:
        UnknownAppenderException - if the appender name is not recognised.
        ConfigurationException - if a error occurred reading the appender configuration.

      • setAlarmLogPeriod

        void setAlarmLogPeriod​(int period)
                throws IllegalArgumentException,
                       ConfigurationException

        Set the interval between periodic active alarm logs.

        Setting the period to 0 will disable periodic alarm logging.

        Parameters:
        period - the interval between active alarm logging, measured in seconds.
        Throws:
        IllegalArgumentException - if the specified period is less than 0 seconds.
        ConfigurationException - if an error occurs updating the logging configuration.

      • getAlarmLogPeriod

        int getAlarmLogPeriod()
               throws ConfigurationException

        Get the interval between periodic active alarm logs.

        Returns:
        the period interval, measured in seconds.
        Throws:
        ConfigurationException - if an error occurs reading the logging configuration.

      • createAppender

        void createAppender​(String name,
                    String pluginName,
                    String[] properties,
                    CompositeData[] components)
             throws com.opencloud.util.exception.ValidationException,
                    ConfigurationException

        Create an appender.

        For example to create a simple file appender:

        createAppender("MyFileAppender", "File", new String[] {"filename=myFile.log"}, null);
        Parameters:
        name - The name of the appender.
        pluginName - the plugin name for the appender.
        properties - The properties specified "name=value" strings in an Array.
        components - Additional components required by this component.
        Throws:
        com.opencloud.util.exception.ValidationException - if a validation error occurs, for example if the properties are incorrectly specified.
        ConfigurationException - if an error occurs creating the appender.
        Since:
        Rhino 2.6.0
        See Also:
        buildGenericComponent(String, String[], CompositeData[])

      • buildGenericComponent

        CompositeData buildGenericComponent​(String pluginName,
                                    String[] properties,
                                    CompositeData[] components)
                             throws ConfigurationException

        Build a generic plugin component. This is used to construct any Log4j 2 plugin, for example filters or layouts.

        For example to create a simple pattern layout:

        buildGenericComponent("PatternLayout", new String[] {"pattern=%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n"}, null);
        Parameters:
        pluginName - the name of the plugin.
        properties - the properties specified "name=value" strings in an Array.
        components - additional components required by this component.
        Returns:
        a composite data object that describes the plugin component configuration.
        Throws:
        ConfigurationException - if an error occurs creating the component.
        Since:
        Rhino 2.6.0

      • getLoggingPropertyNames

        String[] getLoggingPropertyNames()
                          throws ConfigurationException

        Get the set of all known logging properties

        Returns:
        an array of all known properties.
        Throws:
        ConfigurationException - if an error occurs reading the logging configuration.
        Since:
        Rhino 2.6.0

      • getLoggingProperties

        Map<String,​String> getLoggingProperties()
                                       throws ConfigurationException

        Get the set of all logging properties.

        Returns:
        a map of logging property name→value pairs. Both map keys and values are Strings.
        Throws:
        ConfigurationException - if an error occurs reading the logging configuration.
        Since:
        Rhino 2.6.0

      • setLoggingProperty

        void setLoggingProperty​(String name,
                        String value)
                 throws ConfigurationException

        Create or update a logging property. If the property already exists then its value will be replaced with the new value.

        Parameters:
        name - the property name.
        value - the property’s value.
        Throws:
        ConfigurationException - if an error occurs updating the logging configuration.
        Since:
        Rhino 2.6.0

      • setLoggingProperties

        void setLoggingProperties​(Map<String,​String> properties)
                   throws ConfigurationException

        Create or update multiple logging properties. If any property already exists then its value will be replaced with the new value.

        Parameters:
        properties - a map of property name to property value.
        Throws:
        ConfigurationException - if an error occurs updating the logging configuration.
        Since:
        Rhino 2.6.0