Package 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
  Description
  `static final Formatter`
  `AGENT_FILE_FORMATTER`
  Defines the default file formatter as : LOG_LEVEL : message
  `static final 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

  Modifier and Type
  Method
  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, 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 Details

  - ### 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 Details

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