Logger (IBM MobileFirst Foundation Native Android API)

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 level Logger level

SEVERE ERROR

WARNING WARN

INFO INFO

CONFIG LOG

FINE DEBUG

FINER TRACE

FINEST TRACE

JUL level	Logger level
SEVERE	ERROR
WARNING	WARN
INFO	INFO
CONFIG	LOG
FINE	DEBUG
FINER	TRACE
FINEST	TRACE

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Logger.LEVEL
Levels supported in this Logger class.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Logger.LEVEL` Levels supported in this Logger class.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ANALYTICS_FILENAME`
`static boolean`	`DEFAULT_analyticsCapture`
`static boolean`	`DEFAULT_capture`
`static boolean`	`DEFAULT_showLogsInConsole`
`static java.lang.String`	`FILENAME`
`static int`	`MAX_NUM_LOG_FILES`
`static java.lang.String`	`SHARED_PREF_KEY`
`static java.lang.String`	`SHARED_PREF_KEY_CRASH_DETECTED`
`static java.lang.String`	`SHARED_PREF_KEY_filters`
`static java.lang.String`	`SHARED_PREF_KEY_filters_from_server`
`static java.lang.String`	`SHARED_PREF_KEY_level`
`static java.lang.String`	`SHARED_PREF_KEY_level_from_server`
`static java.lang.String`	`SHARED_PREF_KEY_logPersistence`
`static java.lang.String`	`SHARED_PREF_KEY_logPersistence_from_server`
`static java.lang.Object`	`WAIT_LOCK`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated 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`	`doLog(Logger.LEVEL calledLevel, java.lang.String message, long timestamp, JSONObject additionalMetadata, java.lang.Throwable t)`
`static void`	`enter(java.lang.String className, java.lang.String methodName)`
`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.
`static void`	`exit(java.lang.String className, java.lang.String methodName)`
`void`	`fatal(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)` Log at FATAL level.
`static boolean`	`getAnalyticsCapture()`
`static byte[]`	`getByteArrayFromFile(java.io.File file)`
`static boolean`	`getCapture()` Get the current value of the capture flag, indicating that the Logger is recording log calls persistently.
`static java.util.HashMap<java.lang.String,Logger.LEVEL>`	`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 Logger.LEVEL`	`getLevelDefault()`
`static int`	`getMaxFileSize()` Get the current setting for the max file size threshold.
`static boolean`	`getShowLogsInConsole()` Get the current value of the capture flag, indicating that the Logger is recording log calls persistently.
`static JSONObject`	`HashMapToJSONObject(java.util.HashMap<java.lang.String,Logger.LEVEL> pairs)`
`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.
`static java.util.HashMap<java.lang.String,Logger.LEVEL>`	`JSONObjectToHashMap(JSONObject object)`
`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`	`logNetworkData(java.lang.String message)`
`static void`	`processAutomaticTrigger()`
`static void`	`send()` Send the accumulated log data when the persistent log buffer exists and is not empty.
`static void`	`send(WLRequestListener listener)` See `send()`
`static void`	`sendAnalytics(WLRequestListener listener)`
`static void`	`sendIfUnCaughtExceptionDetected(Context context)` Deprecated. since version 6.2; use `send()` with `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`	`setAnalyticsCapture(boolean _capture)`
`static void`	`setAutoSendLogs(boolean _autoSendLogs)` Global setting: turn Auto Log Send on and off.
`static void`	`setAutoSendLogs(boolean _autoSendLogs, int _intervalSeconds)` 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<java.lang.String,Logger.LEVEL> _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.
`static void`	`setShowLogsInConsole(boolean _showLogsInConsole)` Global setting: turn persisting of log data passed to this class's log methods on or off.
`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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - WAIT_LOCK
```
public static final java.lang.Object WAIT_LOCK
```
  - FILENAME
```
public static final java.lang.String FILENAME
```
    See Also:
    
    Constant Field Values
  - ANALYTICS_FILENAME
```
public static final java.lang.String ANALYTICS_FILENAME
```
    See Also:
    
    Constant Field Values
  - SHARED_PREF_KEY
```
public static final java.lang.String SHARED_PREF_KEY
```
  - SHARED_PREF_KEY_CRASH_DETECTED
```
public static final java.lang.String SHARED_PREF_KEY_CRASH_DETECTED
```
    See Also:
    
    Constant Field Values
  - SHARED_PREF_KEY_logPersistence
```
public static final java.lang.String SHARED_PREF_KEY_logPersistence
```
    See Also:
    
    Constant Field Values
  - SHARED_PREF_KEY_level
```
public static final java.lang.String SHARED_PREF_KEY_level
```
    See Also:
    
    Constant Field Values
  - SHARED_PREF_KEY_filters
```
public static final java.lang.String SHARED_PREF_KEY_filters
```
    See Also:
    
    Constant Field Values
  - SHARED_PREF_KEY_logPersistence_from_server
```
public static final java.lang.String SHARED_PREF_KEY_logPersistence_from_server
```
    See Also:
    
    Constant Field Values
  - SHARED_PREF_KEY_level_from_server
```
public static final java.lang.String SHARED_PREF_KEY_level_from_server
```
    See Also:
    
    Constant Field Values
  - SHARED_PREF_KEY_filters_from_server
```
public static final java.lang.String SHARED_PREF_KEY_filters_from_server
```
    See Also:
    
    Constant Field Values
  - DEFAULT_capture
```
public static final boolean DEFAULT_capture
```
    See Also:
    
    Constant Field Values
  - DEFAULT_showLogsInConsole
```
public static final boolean DEFAULT_showLogsInConsole
```
    See Also:
    
    Constant Field Values
  - DEFAULT_analyticsCapture
```
public static final boolean DEFAULT_analyticsCapture
```
    See Also:
    
    Constant Field Values
  - MAX_NUM_LOG_FILES
```
public static final int MAX_NUM_LOG_FILES
```
    See Also:
    
    Constant Field Values
- 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
  - enter
```
public static void enter(java.lang.String className,
                         java.lang.String methodName)
```
  - exit
```
public static void exit(java.lang.String className,
                        java.lang.String methodName)
```
  - logNetworkData
```
public static void logNetworkData(java.lang.String message)
```
  - 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
  - setShowLogsInConsole
```
public static void setShowLogsInConsole(boolean _showLogsInConsole)
```
    Global setting: turn persisting of log data passed to this class's log methods on or off.
    
    Parameters:
    
    _showLogsInConsole - flag to indicate if log data should be saved persistently
  - getShowLogsInConsole
```
public static boolean getShowLogsInConsole()
```
    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
  - 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.
  - setAutoSendLogs
```
public static void setAutoSendLogs(boolean _autoSendLogs,
                                   int _intervalSeconds)
```
    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
    
    _intervalSeconds - interval timer to trigger autosend log
  - 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
  - setAnalyticsCapture
```
public static void setAnalyticsCapture(boolean _capture)
```
    Parameters:
    
    _capture - flag to indicate if analytics data should be saved persistently
  - getAnalyticsCapture
```
public static boolean getAnalyticsCapture()
```
    Returns:
    
    current value of analyticsCapture flag
  - setFilters
```
public static void setFilters(java.util.HashMap<java.lang.String,Logger.LEVEL> _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<java.lang.String,Logger.LEVEL> 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 setCapture(boolean)) turned on.
  - send
```
public static void send(WLRequestListener listener)
```
    See send()
    
    Parameters:
    
    listener - WLRequestListener which specifies an onSuccess callback and an onFailure callback (see WLRequestListener)
  - sendAnalytics
```
public static void sendAnalytics(WLRequestListener listener)
```
    Parameters:
    
    listener - WLRequestListener which specifies an onSuccess callback and an onFailure callback
  - 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 send() with 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 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
  - doLog
```
public void doLog(Logger.LEVEL calledLevel,
                  java.lang.String message,
                  long timestamp,
                  JSONObject additionalMetadata,
                  java.lang.Throwable t)
```
    Parameters:
    
    calledLevel - specify the Logger.LEVEL (a null parameter results in no log entry)
    
    message - (optional) the data for the log entry
    
    timestamp - the number of milliseconds since January 1, 1970, 00:00:00 GMT
    
    t - (optional) an Exception or Throwable, may be null
  - JSONObjectToHashMap
```
public static java.util.HashMap<java.lang.String,Logger.LEVEL> JSONObjectToHashMap(JSONObject object)
```
  - HashMapToJSONObject
```
public static JSONObject HashMapToJSONObject(java.util.HashMap<java.lang.String,Logger.LEVEL> pairs)
```
  - getLevelDefault
```
public static Logger.LEVEL getLevelDefault()
```
  - processAutomaticTrigger
```
public static void processAutomaticTrigger()
```
  - getByteArrayFromFile
```
public static byte[] getByteArrayFromFile(java.io.File file)
                                   throws java.io.UnsupportedEncodingException
```
    Throws:
    
    java.io.UnsupportedEncodingException

Class Logger

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

WAIT_LOCK

FILENAME

ANALYTICS_FILENAME

SHARED_PREF_KEY

SHARED_PREF_KEY_CRASH_DETECTED

SHARED_PREF_KEY_logPersistence

SHARED_PREF_KEY_level

SHARED_PREF_KEY_filters

SHARED_PREF_KEY_logPersistence_from_server

SHARED_PREF_KEY_level_from_server

SHARED_PREF_KEY_filters_from_server

DEFAULT_capture

DEFAULT_showLogsInConsole

DEFAULT_analyticsCapture

MAX_NUM_LOG_FILES

Method Detail

getInstance

enter

exit

logNetworkData

setContext

setLevel

getLevel

setCapture

setShowLogsInConsole

getShowLogsInConsole

setAutoSendLogs

setAutoSendLogs

getCapture

setAnalyticsCapture

getAnalyticsCapture

setFilters

getFilters

setMaxFileSize

getMaxFileSize

send

send

sendAnalytics

updateConfigFromServer

sendIfUnCaughtExceptionDetected

isUnCaughtExceptionDetected

fatal

error

error

error

warn

warn

warn

info

info

log

log

debug

debug

debug

trace

trace

doLog

JSONObjectToHashMap

HashMapToJSONObject

getLevelDefault

processAutomaticTrigger

getByteArrayFromFile