madkit.kernel

## Class AgentLogger

- java.lang.Object
- - java.util.logging.Logger
  - - madkit.kernel.AgentLogger

-     public final class AgentLogger
      extends Logger

  This class defines a logger specialized for MaDKit agents.
  Since:
    MaDKit 5.0.0.5
  Version:
    1
  Author:
    Fabien Michel

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Formatter` | `AGENT_FILE_FORMATTER` Defines the default file formatter as : LOG_LEVEL : message
    `static Formatter` | `AGENT_FORMATTER` Defines the default formatter as : [agent's name] LOG_LEVEL : message

    - ### Fields inherited from class java.util.logging.Logger

      `global, GLOBAL_LOGGER_NAME`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addFileHandler(Path logDirectory, String fileName, boolean append, boolean includeDefaultComment)` Adds a new `FileHandler` to this logger.
    `void` | `addHandler(Handler handler)`
    `void` | `createLogFile()` Creates a default log file for this logger.
    `static void` | `createLogFiles()` Create a log file for each agent having a non `null` logger.
    `void` | `disableCGRWarnings()` Disables the logging of `Level.WARNING` messages related with failed queries over the artificial society.
    `void` | `doNotReactToDebugMode()` Prevents this logger to change its level when `setAllLoggersAtLevelAll()` or `setAllLogLevels(Level)` are used.
    `void` | `enableCGRWarnings()` Enables the logging of `Level.WARNING` messages related with failed queries over the artificial society.
    `BooleanAction` | `getEnableCGRWarningsAction()`
    `Level` | `getWarningLogLevel()` Deprecated. as of MaDKit 5.2, replaced by `enableCGRWarnings()`
    `boolean` | `isCGRWarningsOn()` Tells if CGR warnings (Community, Group, Role) are enabled.
    `boolean` | `isLoggable(Level level)` Check if a message of the given level would actually be logged by this logger.
    `void` | `log(LogRecord record)`
    `static void` | `resetAllLoggersToDefaultLevel()` reset all loggers to the level specified by `Madkit.LevelOption.agentLogLevel`
    `static void` | `setAllLoggersAtLevelAll()` A convenient way of activating a debug session
    `static void` | `setAllLogLevels(Level level)` Set all the agents' loggers to the specified level
    `void` | `setLevel(Level newLevel)` Set the log level for the corresponding agent.
    `void` | `setWarningLogLevel(Level warningLogLevel)` Deprecated. as of MaDKit 5.2, replaced by `enableCGRWarnings()`
    `void` | `severeLog(String message)` This call bypasses any settings and always produces severe log messages whatever the logger's current level.
    `void` | `severeLog(String message, Throwable t)` This call bypasses any settings and always produces severe log messages displaying the stack trace of the throwable if it is not `null`
    `void` | `talk(String msg)` Logs a `TALK` message.
    `String` | `toString()`

    - ### Methods inherited from class java.util.logging.Logger

      `config, config, entering, entering, entering, exiting, exiting, fine, fine, finer, finer, finest, finest, getAnonymousLogger, getAnonymousLogger, getFilter, getGlobal, getHandlers, getLevel, getLogger, getLogger, getName, getParent, getResourceBundle, getResourceBundleName, getUseParentHandlers, info, info, log, log, log, log, log, log, logp, logp, logp, logp, logp, logp, logrb, logrb, logrb, logrb, logrb, logrb, removeHandler, setFilter, setParent, setResourceBundle, setUseParentHandlers, severe, severe, throwing, warning, warning`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### AGENT_FORMATTER

          public static final Formatter AGENT_FORMATTER

      Defines the default formatter as : [agent's name] LOG_LEVEL : message

    - #### AGENT_FILE_FORMATTER

          public static final Formatter AGENT_FILE_FORMATTER

      Defines the default file formatter as : LOG_LEVEL : message

  - ### Method Detail

    - #### setLevel

          public void setLevel(Level newLevel)

      Set the log level for the corresponding agent. If `newLevel` is `Level.ALL` then `enableCGRWarnings()` is automatically triggered.
      Overrides:
        `setLevel` in class `Logger`

    - #### doNotReactToDebugMode

          public void doNotReactToDebugMode()

      Prevents this logger to change its level when `setAllLoggersAtLevelAll()` or `setAllLogLevels(Level)` are used.

    - #### isCGRWarningsOn

          public boolean isCGRWarningsOn()

      Tells if CGR warnings (Community, Group, Role) are enabled.
      Returns:
        `true` if CGR warnings are enabled for this logger
      See Also:
        `enableCGRWarnings()`

    - #### enableCGRWarnings

          public void enableCGRWarnings()

      Enables the logging of `Level.WARNING` messages related with failed queries over the artificial society. For instance, if an agent tries to get agent addresses using `AbstractAgent.getAgentsWithRole(String, String, String)` over a CGR location which does not exist then there will be a warning about that. Since such results could be obtained by agents on purpose, this method provides a convenient way of enabling these kind of traces as will.

    - #### disableCGRWarnings

          public void disableCGRWarnings()

      Disables the logging of `Level.WARNING` messages related with failed queries over the artificial society.
      See Also:
        `enableCGRWarnings()`

    - #### getEnableCGRWarningsAction

          public BooleanAction getEnableCGRWarningsAction()

      Returns:
        an `Action` for building UI with this feature

    - #### createLogFile

          public void createLogFile()

      Creates a default log file for this logger. This call is equivalent to `addLogFile(null, null, false, true)` This file will be located in the directory specified by the MaDKit property `Madkit.Option.logDirectory`, which is set to "logs" by default.
      See Also:
        `addFileHandler(Path, String, boolean, boolean)`

    - #### addFileHandler

          public void addFileHandler(Path logDirectory,
                                     String fileName,
                                     boolean append,
                                     boolean includeDefaultComment)

      Adds a new `FileHandler` to this logger. This method provides an easy way of creating a new file handler with an agent formatting and with a corresponding file located in a specified directory. The related file will be located in the directory specified by the MaDKit property `Madkit.Option.logDirectory`, which is set to "logs" followed by a directory named according to the date of the run.
      Parameters:
        `logDirectory` - the logDirectory to be used may be `null`, in which case the file will be located in the directory specified by the MaDKit property `Madkit.Option.logDirectory` which is set to "logs" by default.
        `fileName` - may be `null`, in which case `Logger.getName()` is used
        `append` - if `true`, then bytes will be written to the end of the file rather than the beginning
        `includeDefaultComment` - if `true`, includes comments displaying creation and closing dates
      See Also:
        `FileHandler`

    - #### addHandler

          public void addHandler(Handler handler)

      Overrides:
        `addHandler` in class `Logger`

    - #### talk

          public void talk(String msg)

      Logs a `TALK` message. This uses a special level which could be used to produce messages that will be rendered as they are, without any formatting work nor end-of-line character.

      If the logger's level is not `Level.OFF` then the given message is forwarded to all the registered output Handler objects.

      If the logger's level is `Level.OFF` then the message is only printed to `System.out`

      Parameters:
        `msg` - The string message

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### log

          public void log(LogRecord record)

      Overrides:
        `log` in class `Logger`

    - #### isLoggable

          public boolean isLoggable(Level level)

      Check if a message of the given level would actually be logged by this logger. This check is based on the Loggers effective level, which may be inherited from its parent.
      Overrides:
        `isLoggable` in class `Logger`
      Parameters:
        `level` - a message logging level
      Returns:
        true if the given message level is currently being logged.

    - #### severeLog

          public void severeLog(String message,
                                Throwable t)

      This call bypasses any settings and always produces severe log messages displaying the stack trace of the throwable if it is not `null`
      Parameters:
        `message` - the message to display
        `t` - the related exception if any. It can be `null`

    - #### severeLog

          public void severeLog(String message)

      This call bypasses any settings and always produces severe log messages whatever the logger's current level.
      Parameters:
        `message` - the message to display

    - #### setAllLogLevels

          public static void setAllLogLevels(Level level)

      Set all the agents' loggers to the specified level
      Parameters:
        `level` - the new level

    - #### setAllLoggersAtLevelAll

          public static void setAllLoggersAtLevelAll()

      A convenient way of activating a debug session

    - #### resetAllLoggersToDefaultLevel

          public static void resetAllLoggersToDefaultLevel()

      reset all loggers to the level specified by `Madkit.LevelOption.agentLogLevel`

    - #### createLogFiles

          public static void createLogFiles()

      Create a log file for each agent having a non `null` logger.
      See Also:
        `createLogFile()`

    - #### getWarningLogLevel

          @Deprecated
          public Level getWarningLogLevel()

      Deprecated. as of MaDKit 5.2, replaced by `enableCGRWarnings()`
      now useless.

    - #### setWarningLogLevel

          @Deprecated
          public void setWarningLogLevel(Level warningLogLevel)

      Deprecated. as of MaDKit 5.2, replaced by `enableCGRWarnings()`
      now useless.

Fabien Michel, Olivier Gutknecht, Jacques Ferber - February 17 2020