com.worklight.common

Class Logger

  • java.lang.Object
    • com.worklight.common.Logger


  • public final class Logger
    extends java.lang.Object
    Logger is an abstraction of, and pass through to, android.util.Log. Logger provides some enhanced capability such as capturing log calls, package filtering, and log level control at both global and individual package scope. It also provides a method call to send captured logs to the IBM MobileFirst Platform server. When this Logger class's capture flag is turned on via setCapture(true) method call, all messages passed through this class's log methods will be persisted to store in the following JSON object format:

     {
       "timestamp"    : "17-02-2013 13:54:27:123",  // "dd-MM-yyyy hh:mm:ss:S"
       "level"        : "ERROR",                    // FATAL || ERROR || WARN || INFO || LOG || DEBUG || TRACE
       "package"      : "your_tag",                 // typically a class name, app name, or JavaScript object name
       "msg"          : "the message",              // a helpful log message
       "metadata"     : {"hi": "world"},            // (optional) additional JSON metadata, appended via doLog API call
       "threadid"     : long                        // (optional) id of the current thread
     }
     

    Log data is accumulated persistently to a log file until the file size is greater than FILE_SIZE_LOG_THRESHOLD. At this point the log file is rolled over. Log data will only be captured oncecom.worklight.common.Logger.setContext(Context) is called. Once both files are full, the oldest log data is pushed out to make room for new log data.

    Log file data is sent to the IBM MobileFirst Platform server when this class's send() method is called and the accumulated log size is greater than zero. When the log data is successfully uploaded, the persisted local log data is deleted.

    All of this class's method calls, such as info(String), are pass-throughs to the equivalent method call in android.util.Logger when the LEVEL log function called is at or above the set LEVEL.

    As a convenience, this Logger also sets a global java.util.logging.Handler. Developers who would rather use java.util.logging.Logger API may do so, with the understanding that java.util.logging.Logger API calls will not be captured until com.worklight.common.Logger.setContext(Context) is called. The mapping of java.util.logging.Level to com.worklight.common.LEVEL is:

    JUL levelLogger level
    SEVEREERROR
    WARNINGWARN
    INFOINFO
    CONFIGLOG
    FINEDEBUG
    FINERTRACE
    FINESTTRACE

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class and Description
      protected static class  Logger.FileLoggerInterface 
      static class  Logger.LEVEL
      Levels supported in this Logger class.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void debug(java.lang.String message)
      Log at DEBUG level.
      void debug(java.lang.String message, JSONObject additionalMetadata)
      Log at DEBUG level.
      void debug(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
      Log at DEBUG level.
      void error(java.lang.String message)
      Log at ERROR level.
      void error(java.lang.String message, JSONObject additionalMetadata)
      Log at ERROR level.
      void error(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
      Log at ERROR level.
      void fatal(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
      Log at FATAL level.
      static boolean getCapture()
      Get the current value of the capture flag, indicating that the Logger is recording log calls persistently.
      static java.util.HashMap getFilters()
      Get the current list of filters.
      static Logger getInstance(java.lang.String tag)
      Get or create an instance of this logger.
      static Logger.LEVEL getLevel()
      Get the current Logger.LEVEL.
      static int getMaxFileSize()
      Get the current setting for the max file size threshold.
      void info(java.lang.String message)
      Log at INFO level.
      void info(java.lang.String message, JSONObject additionalMetadata)
      Log at INFO level.
      static boolean isUnCaughtExceptionDetected()
      Ask the Logger if an uncaught exception, which often appears to the user as a crashed app, is present in the persistent capture buffer.
      void log(java.lang.String message)
      Log at LOG (Android VERBOSE) level.
      void log(java.lang.String message, JSONObject additionalMetadata)
      Log at LOG (Android VERBOSE) level.
      static void send()
      Send the accumulated log data when the persistent log buffer exists and is not empty.
      static void send(WLRequestListener listener)
      static void sendIfUnCaughtExceptionDetected(Context context)
      Deprecated. 
      since version 6.2; use Logger.send() with Logger.isUnCaughtExceptionDetected() conditional instead.

      Send the log file when there is an uncaught exception detected, and was recorded to the log buffer due to capture being turned on at the time of the uncaught exception.

      This is a convenience method so that callers may place a single line of code at the point in their application where they want to call it.

      static void setAutoSendLogs(boolean _autoSendLogs)
      Global setting: turn Auto Log Send on and off.
      static void setCapture(boolean _capture)
      Global setting: turn persisting of log data passed to this class's log methods on or off.
      static void setContext(Context _context)
      Context object must be set in order to use the Logger API.
      static void setFilters(java.util.HashMap _filters)
      Filter on packages at and above designated LEVEL.
      static void setLevel(Logger.LEVEL desiredLevel)
      Set the level and above at which log messages should be saved/printed.
      static void setMaxFileSize(int bytes)
      Set the maximum size of the local log file.
      void trace(java.lang.String message)
      Log at TRACE level.
      void trace(java.lang.String message, JSONObject additionalMetadata)
      Log at TRACE level.
      static void updateConfigFromServer()
      Get and apply the configuration from the IBM MobileFirst Platform Server.
      void warn(java.lang.String message)
      Log at WARN level.
      void warn(java.lang.String message, JSONObject additionalMetadata)
      Log at WARN level.
      void warn(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
      Log at WARN level.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • getInstance

        public static Logger getInstance(java.lang.String tag)
        Get or create an instance of this logger. If an instance already exists for 'tag' parameter, that instance will be returned.
        Parameters:
        tag - the package or tag that should be printed with log messages. The value is passed through to android.util.Log and persistently recorded when log capture is enabled.
        Returns:
        an instance of this class
      • setContext

        public static void setContext(Context _context)
        Context object must be set in order to use the Logger API. This is called automatically by WL.init. setContext should only be called once. Any subsequent calls will be a no-op. If the configuration needs to be changed, use the getters and setters provided.
        Parameters:
        _context - Android Context object
      • setLevel

        public static void setLevel(Logger.LEVEL desiredLevel)
        Set the level and above at which log messages should be saved/printed. For example, passing LEVEL.INFO will log INFO, WARN, ERROR, and FATAL. A null parameter value is ignored and has no effect.
        Parameters:
        desiredLevel - @see LEVEL
      • getLevel

        public static Logger.LEVEL getLevel()
        Get the current Logger.LEVEL.
        Returns:
        Logger.LEVEL
      • setCapture

        public static void setCapture(boolean _capture)
        Global setting: turn persisting of log data passed to this class's log methods on or off.
        Parameters:
        _capture - flag to indicate if log data should be saved persistently
      • setAutoSendLogs

        public static void setAutoSendLogs(boolean _autoSendLogs)
        Global setting: turn Auto Log Send on and off.
        Parameters:
        _autoSendLogs - flag to indicate if log data should be sent automatically after each successful resource request, if no logging has occurred within 60 seconds.
      • getCapture

        public static boolean getCapture()
        Get the current value of the capture flag, indicating that the Logger is recording log calls persistently. Default behavior is to retrieve on successful WLClient.connect and WLClient.invokeProcedure.
        Returns:
        current value of capture flag
      • setFilters

        public static void setFilters(java.util.HashMap _filters)
        Filter on packages at and above designated LEVEL. This is a white list. Any package not listed in the filters will not be logged. Pass null or an empty HashMap parameter to remove filters and resume logging at the default LEVEL.
        Parameters:
        _filters - set of filters and associated level (and above) to allow for logging
      • getFilters

        public static java.util.HashMap getFilters()
        Get the current list of filters.
        Returns:
        map of white list package filters and the designated LEVEL
      • setMaxFileSize

        public static void setMaxFileSize(int bytes)
        Set the maximum size of the local log file. Once the maximum file size is reached, no more data will be appended. Consider that this file is sent to a server.
        Parameters:
        bytes - maximum size of the file in bytes, minimum 10000
      • getMaxFileSize

        public static int getMaxFileSize()
        Get the current setting for the max file size threshold.
        Returns:
        current max file size threshold
      • send

        public static void send()
        Send the accumulated log data when the persistent log buffer exists and is not empty. The data accumulates in the log buffer from the use of Logger with capture (see Logger.setCapture(boolean)) turned on.
      • send

        public static void send(WLRequestListener listener)
        Parameters:
        listener - WLRequestListener which specifies an onSuccess callback and an onFailure callback (see com.worklight.wlclient.WLRequestListener)
      • updateConfigFromServer

        public static void updateConfigFromServer()
        Get and apply the configuration from the IBM MobileFirst Platform Server. The configuration comes from the use of the "Config Profiles" tab in the IBM MobileFirst Platform administrative console.
      • sendIfUnCaughtExceptionDetected

        @Deprecated
        public static void sendIfUnCaughtExceptionDetected(Context context)
        Deprecated. since version 6.2; use Logger.send() with Logger.isUnCaughtExceptionDetected() conditional instead.

        Send the log file when there is an uncaught exception detected, and was recorded to the log buffer due to capture being turned on at the time of the uncaught exception.

        This is a convenience method so that callers may place a single line of code at the point in their application where they want to call it.

        Parameters:
        context - the Android Context in which this method should be run; typically an Activity instance.
      • isUnCaughtExceptionDetected

        public static boolean isUnCaughtExceptionDetected()
        Ask the Logger if an uncaught exception, which often appears to the user as a crashed app, is present in the persistent capture buffer. This method should not be called before Logger.setContext(Context). If it is called too early, an error message is issued and false is returned.
        Returns:
        boolean if an uncaught exception log entry is currently in the persistent log buffer
      • fatal

        public void fatal(java.lang.String message,
                 JSONObject additionalMetadata,
                 java.lang.Throwable t)
        Log at FATAL level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
        t - a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
      • error

        public void error(java.lang.String message)
        Log at ERROR level.
        Parameters:
        message - the message to log
      • error

        public void error(java.lang.String message,
                 JSONObject additionalMetadata)
        Log at ERROR level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
      • error

        public void error(java.lang.String message,
                 JSONObject additionalMetadata,
                 java.lang.Throwable t)
        Log at ERROR level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
        t - a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
      • warn

        public void warn(java.lang.String message)
        Log at WARN level.
        Parameters:
        message -
      • warn

        public void warn(java.lang.String message,
                JSONObject additionalMetadata)
        Log at WARN level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
      • warn

        public void warn(java.lang.String message,
                JSONObject additionalMetadata,
                java.lang.Throwable t)
        Log at WARN level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
        t - a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
      • info

        public void info(java.lang.String message)
        Log at INFO level.
        Parameters:
        message - the message to log
      • info

        public void info(java.lang.String message,
                JSONObject additionalMetadata)
        Log at INFO level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
      • log

        public void log(java.lang.String message)
        Log at LOG (Android VERBOSE) level.
        Parameters:
        message - the message to log
      • log

        public void log(java.lang.String message,
               JSONObject additionalMetadata)
        Log at LOG (Android VERBOSE) level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
      • debug

        public void debug(java.lang.String message)
        Log at DEBUG level.
        Parameters:
        message - the message to log
      • debug

        public void debug(java.lang.String message,
                 JSONObject additionalMetadata)
        Log at DEBUG level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
      • debug

        public void debug(java.lang.String message,
                 JSONObject additionalMetadata,
                 java.lang.Throwable t)
        Log at DEBUG level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output
        t - a Throwable whose stack trace is converted to string and logged, and passed through as-is to android.util.Log
      • trace

        public void trace(java.lang.String message)
        Log at TRACE level.
        Parameters:
        message - the message to log
      • trace

        public void trace(java.lang.String message,
                 JSONObject additionalMetadata)
        Log at TRACE level.
        Parameters:
        message - the message to log
        additionalMetadata - to append to log output


© Copyright IBM Corp. 2006, 2015. All Rights Reserved.