Logger (Java client-side API for native Android apps)

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

protected static class Logger.FileLoggerInterface

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

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(com.worklight.wlclient.WLRequestListener listener)` See `Logger.send()`
`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(com.worklight.wlclient.WLRequestListener listener)
```
    See Logger.send()
    
    Parameters:
    listener - WLRequestListener which specifies an onSuccess callback and an onFailure callback (see 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

Methods inherited from class java.lang.Object

getInstance

setContext

setLevel

getLevel

setCapture

setAutoSendLogs

getCapture

setFilters

getFilters

setMaxFileSize

getMaxFileSize

send

send

updateConfigFromServer

sendIfUnCaughtExceptionDetected

isUnCaughtExceptionDetected

fatal

error

error

error

warn

warn

warn

info

info

log

log

debug

debug

debug

trace

trace