Package com.elvishew.xlog

Class XLog

java.lang.Object

com.elvishew.xlog.XLog

public class XLog
extends java.lang.Object

A log tool which can be used in android or java, the most important feature is it can print the logs to multiple place in the same time, such as android shell, console and file, you can even print the log to the remote server if you want, all of these can be done just within one calling.
Also, XLog is very flexible, almost every component is replaceable.

How to use in a general way:

1. Initial the log system.
Using one of
init()
init(int),
init(LogConfiguration)
init(Printer...),
init(int, Printer...),
init(LogConfiguration, Printer...),
that will setup a Logger for a global usage. If you want to use a customized configuration instead of the global one to log something, you can start a customization logging.

For android, a best place to do the initialization is Application.onCreate().

2. Start to log.
v(String, Object...), v(String) and v(String, Throwable) are for logging a LogLevel.VERBOSE message.
d(String, Object...), d(String) and d(String, Throwable) are for logging a LogLevel.DEBUG message.
i(String, Object...), i(String) and i(String, Throwable) are for logging a LogLevel.INFO message.
w(String, Object...), w(String) and w(String, Throwable) are for logging a LogLevel.WARN message.
e(String, Object...), e(String) and e(String, Throwable) are for logging a LogLevel.ERROR message.
log(int, String, Object...), log(int, String) and log(int, String, Throwable) are for logging a specific level message.
json(String) is for logging a LogLevel.DEBUG JSON string.
xml(String) is for logging a LogLevel.DEBUG XML string.
Also, you can directly log any object with specific log level, like v(Object), and any object array with specific log level, like v(Object[]).

How to use in a dynamically customizing way after initializing the log system:

1. Start a customization.
Call any of
logLevel(int)
tag(String),
enableThreadInfo(),
disableThreadInfo(),
enableStackTrace(int),
enableStackTrace(String, int),
disableStackTrace(),
enableBorder(),
disableBorder(),
jsonFormatter(JsonFormatter),
xmlFormatter(XmlFormatter),
threadFormatter(ThreadFormatter),
stackTraceFormatter(StackTraceFormatter),
throwableFormatter(ThrowableFormatter)
borderFormatter(BorderFormatter)
addObjectFormatter(Class, ObjectFormatter)
addInterceptor(Interceptor)
printers(Printer...),
it will return a Logger.Builder object.

2. Finish the customization.
Continue to setup other fields of the returned Logger.Builder.

3. Build a dynamically generated Logger.
Call the Logger.Builder.build() of the returned Logger.Builder.

4. Start to log.
The logging methods of a Logger is completely same as that ones in XLog.
As a convenience, you can ignore the step 3, just call the logging methods of Logger.Builder, it will automatically build a Logger and call the target logging method.

Compatibility:

In order to be compatible with Log, all the methods of Log are supported here. See:
XLog.Log.v(String, String), XLog.Log.v(String, String, Throwable)
XLog.Log.d(String, String), XLog.Log.d(String, String, Throwable)
XLog.Log.i(String, String), XLog.Log.i(String, String, Throwable)
XLog.Log.w(String, String), XLog.Log.w(String, String, Throwable)
XLog.Log.wtf(String, String), XLog.Log.wtf(String, String, Throwable)
XLog.Log.e(String, String), XLog.Log.e(String, String, Throwable)
XLog.Log.println(int, String, String)
XLog.Log.isLoggable(String, int)
XLog.Log.getStackTraceString(Throwable)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	XLog.Log	Deprecated. please use XLog instead

Method Summary

Modifier and Type	Method	Description
static Logger.Builder	addInterceptor(Interceptor interceptor)	Start to customize a Logger and add an interceptor.
static <T> Logger.Builder	addObjectFormatter(java.lang.Class<T> objectClass, ObjectFormatter<? super T> objectFormatter)	Start to customize a Logger and add an object formatter for specific class of object.
static Logger.Builder	b()	Deprecated. use enableBorder() instead, since 1.7.0
static Logger.Builder	borderFormatter(BorderFormatter borderFormatter)	Start to customize a Logger and set the BorderFormatter.
static void	d(java.lang.Object object)	Log an object with level LogLevel.DEBUG.
static void	d(java.lang.Object[] array)	Log an array with level LogLevel.DEBUG.
static void	d(java.lang.String msg)	Log a message with level LogLevel.DEBUG.
static void	d(java.lang.String format, java.lang.Object... args)	Log a message with level LogLevel.DEBUG.
static void	d(java.lang.String msg, java.lang.Throwable tr)	Log a message and a throwable with level LogLevel.DEBUG.
static Logger.Builder	disableBorder()	Start to customize a Logger and disable border, the log content won't be surrounded by a border.
static Logger.Builder	disableStackTrace()	Start to customize a Logger and disable stack trace, the stack trace won't be printed with the log message.
static Logger.Builder	disableThreadInfo()	Start to customize a Logger and disable thread info, the thread info won't be printed with the log message.
static void	e(java.lang.Object object)	Log an object with level LogLevel.ERROR.
static void	e(java.lang.Object[] array)	Log an array with level LogLevel.ERROR.
static void	e(java.lang.String msg)	Log a message with level LogLevel.ERROR.
static void	e(java.lang.String format, java.lang.Object... args)	Log a message with level LogLevel.ERROR.
static void	e(java.lang.String msg, java.lang.Throwable tr)	Log a message and a throwable with level LogLevel.ERROR.
static Logger.Builder	enableBorder()	Start to customize a Logger and enable border, the border would surround the entire log content, and separate the log message, thread info and stack trace.
static Logger.Builder	enableStackTrace(int depth)	Start to customize a Logger and enable stack trace, the stack trace would be printed with the log message.
static Logger.Builder	enableStackTrace(java.lang.String stackTraceOrigin, int depth)	Start to customize a Logger and enable stack trace, the stack trace would be printed with the log message.
static Logger.Builder	enableThreadInfo()	Start to customize a Logger and enable thread info, the thread info would be printed with the log message.
static void	i(java.lang.Object object)	Log an object with level LogLevel.INFO.
static void	i(java.lang.Object[] array)	Log an array with level LogLevel.INFO.
static void	i(java.lang.String msg)	Log a message with level LogLevel.INFO.
static void	i(java.lang.String format, java.lang.Object... args)	Log a message with level LogLevel.INFO.
static void	i(java.lang.String msg, java.lang.Throwable tr)	Log a message and a throwable with level LogLevel.INFO.
static void	init()	Initialize log system, should be called only once.
static void	init(int logLevel)	Initialize log system, should be called only once.
static void	init(int logLevel, LogConfiguration logConfiguration)	Deprecated. the log level is part of log configuration now, use init(LogConfiguration) instead, since 1.3.0
static void	init(int logLevel, LogConfiguration logConfiguration, Printer... printers)	Deprecated. the log level is part of log configuration now, use init(LogConfiguration, Printer...) instead, since 1.3.0
static void	init(int logLevel, Printer... printers)	Initialize log system, should be called only once.
static void	init(LogConfiguration logConfiguration)	Initialize log system, should be called only once.
static void	init(LogConfiguration logConfiguration, Printer... printers)	Initialize log system, should be called only once.
static void	init(Printer... printers)	Initialize log system, should be called only once.
static void	json(java.lang.String json)	Log a JSON string, with level LogLevel.DEBUG by default.
static Logger.Builder	jsonFormatter(JsonFormatter jsonFormatter)	Start to customize a Logger and set the JsonFormatter.
static void	log(int logLevel, java.lang.Object object)	Log an object with specific log level.
static void	log(int logLevel, java.lang.Object[] array)	Log an array with specific log level.
static void	log(int logLevel, java.lang.String msg)	Log a message with specific log level.
static void	log(int logLevel, java.lang.String format, java.lang.Object... args)	Log a message with specific log level.
static void	log(int logLevel, java.lang.String msg, java.lang.Throwable tr)	Log a message and a throwable with specific log level.
static Logger.Builder	logLevel(int logLevel)	Start to customize a Logger and set the log level.
static Logger.Builder	nb()	Deprecated. use disableBorder() instead, since 1.7.0
static Logger.Builder	nst()	Deprecated. use disableStackTrace() instead, since 1.7.0
static Logger.Builder	nt()	Deprecated. use disableThreadInfo() instead, since 1.7.0
static Logger.Builder	printers(Printer... printers)	Start to customize a Logger and set the Printer array.
static Logger.Builder	st(int depth)	Deprecated. use enableStackTrace(int) instead, since 1.7.0
static Logger.Builder	st(java.lang.String stackTraceOrigin, int depth)	Deprecated. use enableStackTrace(String, int) instead, since 1.7.0
static Logger.Builder	stackTraceFormatter(StackTraceFormatter stackTraceFormatter)	Start to customize a Logger and set the StackTraceFormatter.
static Logger.Builder	t()	Deprecated. use enableThreadInfo() instead, since 1.7.0
static Logger.Builder	tag(java.lang.String tag)	Start to customize a Logger and set the tag.
static Logger.Builder	threadFormatter(ThreadFormatter threadFormatter)	Start to customize a Logger and set the ThreadFormatter.
static Logger.Builder	throwableFormatter(ThrowableFormatter throwableFormatter)	Start to customize a Logger and set the ThrowableFormatter.
static void	v(java.lang.Object object)	Log an object with level LogLevel.VERBOSE.
static void	v(java.lang.Object[] array)	Log an array with level LogLevel.VERBOSE.
static void	v(java.lang.String msg)	Log a message with level LogLevel.VERBOSE.
static void	v(java.lang.String format, java.lang.Object... args)	Log a message with level LogLevel.VERBOSE.
static void	v(java.lang.String msg, java.lang.Throwable tr)	Log a message and a throwable with level LogLevel.VERBOSE.
static void	w(java.lang.Object object)	Log an object with level LogLevel.WARN.
static void	w(java.lang.Object[] array)	Log an array with level LogLevel.WARN.
static void	w(java.lang.String msg)	Log a message with level LogLevel.WARN.
static void	w(java.lang.String format, java.lang.Object... args)	Log a message with level LogLevel.WARN.
static void	w(java.lang.String msg, java.lang.Throwable tr)	Log a message and a throwable with level LogLevel.WARN.
static void	xml(java.lang.String xml)	Log a XML string, with level LogLevel.DEBUG by default.
static Logger.Builder	xmlFormatter(XmlFormatter xmlFormatter)	Start to customize a Logger and set the XmlFormatter.

Methods inherited from class java.lang.Object

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

Method Detail

init

public static void init()

Initialize log system, should be called only once.

Since:

1.3.0

init

public static void init(int logLevel)

Initialize log system, should be called only once.

Parameters:

logLevel - the log level, logs with a lower level than which would not be printed

init

@Deprecated
public static void init(int logLevel,
                        LogConfiguration logConfiguration)

Deprecated.

the log level is part of log configuration now, use init(LogConfiguration) instead, since 1.3.0

Initialize log system, should be called only once.

Parameters:

logLevel - the log level, logs with a lower level than which would not be printed

logConfiguration - the log configuration

init

public static void init(LogConfiguration logConfiguration)

Initialize log system, should be called only once.

Parameters:

logConfiguration - the log configuration

Since:

1.3.0

init

public static void init(Printer... printers)

Initialize log system, should be called only once.

Parameters:

printers - the printers, each log would be printed by all of the printers

Since:

1.3.0

init

public static void init(int logLevel,
                        Printer... printers)

Initialize log system, should be called only once.

Parameters:

logLevel - the log level, logs with a lower level than which would not be printed

printers - the printers, each log would be printed by all of the printers

init

@Deprecated
public static void init(int logLevel,
                        LogConfiguration logConfiguration,
                        Printer... printers)

Deprecated.

the log level is part of log configuration now, use init(LogConfiguration, Printer...) instead, since 1.3.0

Initialize log system, should be called only once.

Parameters:

logLevel - the log level, logs with a lower level than which would not be printed

logConfiguration - the log configuration

printers - the printers, each log would be printed by all of the printers

init

public static void init(LogConfiguration logConfiguration,
                        Printer... printers)

Initialize log system, should be called only once.

Parameters:

logConfiguration - the log configuration

printers - the printers, each log would be printed by all of the printers

Since:

1.3.0

logLevel

public static Logger.Builder logLevel(int logLevel)

Start to customize a Logger and set the log level.

Parameters:

logLevel - the log level to customize

Returns:

the Logger.Builder to build the Logger

Since:

1.3.0

tag

public static Logger.Builder tag(java.lang.String tag)

Start to customize a Logger and set the tag.

Parameters:

tag - the tag to customize

Returns:

the Logger.Builder to build the Logger

t

@Deprecated
public static Logger.Builder t()

Deprecated.

use enableThreadInfo() instead, since 1.7.0

Start to customize a Logger and enable thread info.

Returns:

the Logger.Builder to build the Logger

enableThreadInfo

public static Logger.Builder enableThreadInfo()

Start to customize a Logger and enable thread info, the thread info would be printed with the log message.

Returns:

the Logger.Builder to build the Logger

Since:

1.7.0

See Also:

ThreadFormatter

nt

@Deprecated
public static Logger.Builder nt()

Deprecated.

use disableThreadInfo() instead, since 1.7.0

Start to customize a Logger and disable thread info.

Returns:

the Logger.Builder to build the Logger

disableThreadInfo

public static Logger.Builder disableThreadInfo()

Start to customize a Logger and disable thread info, the thread info won't be printed with the log message.

Returns:

the Logger.Builder to build the Logger

Since:

1.7.0

st

@Deprecated
public static Logger.Builder st(int depth)

Deprecated.

use enableStackTrace(int) instead, since 1.7.0

Start to customize a Logger and enable stack trace.

Parameters:

depth - the number of stack trace elements we should log, 0 if no limitation

Returns:

the Logger.Builder to build the Logger

enableStackTrace

public static Logger.Builder enableStackTrace(int depth)

Start to customize a Logger and enable stack trace, the stack trace would be printed with the log message.

Parameters:

depth - the number of stack trace elements we should log, 0 if no limitation

Returns:

the Logger.Builder to build the Logger

Since:

1.7.0

See Also:

StackTraceFormatter

st

@Deprecated
public static Logger.Builder st(java.lang.String stackTraceOrigin,
                                int depth)

Deprecated.

use enableStackTrace(String, int) instead, since 1.7.0

Start to customize a Logger and enable stack trace.

Parameters:

stackTraceOrigin - the origin of stack trace elements from which we should NOT log, it can be a package name like "com.elvishew.xlog", a class name like "com.yourdomain.logWrapper", or something else between package name and class name, like "com.yourdomain.". It is mostly used when you are using a logger wrapper

depth - the number of stack trace elements we should log, 0 if no limitation

Returns:

the Logger.Builder to build the Logger

Since:

1.4.0

enableStackTrace

public static Logger.Builder enableStackTrace(java.lang.String stackTraceOrigin,
                                              int depth)

Start to customize a Logger and enable stack trace, the stack trace would be printed with the log message.

Parameters:

stackTraceOrigin - the origin of stack trace elements from which we should NOT log, it can be a package name like "com.elvishew.xlog", a class name like "com.yourdomain.logWrapper", or something else between package name and class name, like "com.yourdomain.". It is mostly used when you are using a logger wrapper

depth - the number of stack trace elements we should log, 0 if no limitation

Returns:

the Logger.Builder to build the Logger

Since:

1.7.0

See Also:

StackTraceFormatter

nst

@Deprecated
public static Logger.Builder nst()

Deprecated.

use disableStackTrace() instead, since 1.7.0

Start to customize a Logger and disable stack trace.

Returns:

the Logger.Builder to build the Logger

disableStackTrace

public static Logger.Builder disableStackTrace()

Start to customize a Logger and disable stack trace, the stack trace won't be printed with the log message.

Returns:

the Logger.Builder to build the Logger

Since:

1.7.0

b

@Deprecated
public static Logger.Builder b()

Deprecated.

use enableBorder() instead, since 1.7.0

Start to customize a Logger and enable border.

Returns:

the Logger.Builder to build the Logger

enableBorder

public static Logger.Builder enableBorder()

Start to customize a Logger and enable border, the border would surround the entire log content, and separate the log message, thread info and stack trace.

Returns:

the Logger.Builder to build the Logger

Since:

1.7.0

See Also:

BorderFormatter

nb

@Deprecated
public static Logger.Builder nb()

Deprecated.

use disableBorder() instead, since 1.7.0

Start to customize a Logger and disable border.

Returns:

the Logger.Builder to build the Logger

disableBorder

public static Logger.Builder disableBorder()

Start to customize a Logger and disable border, the log content won't be surrounded by a border.

Returns:

the Logger.Builder to build the Logger

Since:

1.7.0

jsonFormatter

public static Logger.Builder jsonFormatter(JsonFormatter jsonFormatter)

Start to customize a Logger and set the JsonFormatter.

Parameters:

jsonFormatter - the JsonFormatter to customize

Returns:

the Logger.Builder to build the Logger

xmlFormatter

public static Logger.Builder xmlFormatter(XmlFormatter xmlFormatter)

Start to customize a Logger and set the XmlFormatter.

Parameters:

xmlFormatter - the XmlFormatter to customize

Returns:

the Logger.Builder to build the Logger

throwableFormatter

public static Logger.Builder throwableFormatter(ThrowableFormatter throwableFormatter)

Start to customize a Logger and set the ThrowableFormatter.

Parameters:

throwableFormatter - the ThrowableFormatter to customize

Returns:

the Logger.Builder to build the Logger

threadFormatter

public static Logger.Builder threadFormatter(ThreadFormatter threadFormatter)

Start to customize a Logger and set the ThreadFormatter.

Parameters:

threadFormatter - the ThreadFormatter to customize

Returns:

the Logger.Builder to build the Logger

stackTraceFormatter

public static Logger.Builder stackTraceFormatter(StackTraceFormatter stackTraceFormatter)

Start to customize a Logger and set the StackTraceFormatter.

Parameters:

stackTraceFormatter - the StackTraceFormatter to customize

Returns:

the Logger.Builder to build the Logger

borderFormatter

public static Logger.Builder borderFormatter(BorderFormatter borderFormatter)

Start to customize a Logger and set the BorderFormatter.

Parameters:

borderFormatter - the BorderFormatter to customize

Returns:

the Logger.Builder to build the Logger

addObjectFormatter

public static <T> Logger.Builder addObjectFormatter(java.lang.Class<T> objectClass,
                                                    ObjectFormatter<? super T> objectFormatter)

Start to customize a Logger and add an object formatter for specific class of object.

Type Parameters:

T - the type of object

Parameters:

objectClass - the class of object

objectFormatter - the object formatter to add

Returns:

the Logger.Builder to build the Logger

Since:

1.1.0

addInterceptor

public static Logger.Builder addInterceptor(Interceptor interceptor)

Start to customize a Logger and add an interceptor.

Parameters:

interceptor - the interceptor to add

Returns:

the Logger.Builder to build the Logger

Since:

1.3.0

printers

public static Logger.Builder printers(Printer... printers)

Start to customize a Logger and set the Printer array.

Parameters:

printers - the Printer array to customize

Returns:

the Logger.Builder to build the Logger

v

public static void v(java.lang.Object object)

Log an object with level LogLevel.VERBOSE.

Parameters:

object - the object to log

Since:

1.1.0

See Also:

LogConfiguration.Builder.addObjectFormatter(Class, ObjectFormatter)

v

public static void v(java.lang.Object[] array)

Log an array with level LogLevel.VERBOSE.

Parameters:

array - the array to log

v

public static void v(java.lang.String format,
                     java.lang.Object... args)

Log a message with level LogLevel.VERBOSE.

Parameters:

format - the format of the message to log

args - the arguments of the message to log

v

public static void v(java.lang.String msg)

Log a message with level LogLevel.VERBOSE.

Parameters:

msg - the message to log

v

public static void v(java.lang.String msg,
                     java.lang.Throwable tr)

Log a message and a throwable with level LogLevel.VERBOSE.

Parameters:

msg - the message to log

tr - the throwable to be log

d

public static void d(java.lang.Object object)

Log an object with level LogLevel.DEBUG.

Parameters:

object - the object to log

Since:

1.1.0

See Also:

LogConfiguration.Builder.addObjectFormatter(Class, ObjectFormatter)

d

public static void d(java.lang.Object[] array)

Log an array with level LogLevel.DEBUG.

Parameters:

array - the array to log

d

public static void d(java.lang.String format,
                     java.lang.Object... args)

Log a message with level LogLevel.DEBUG.

Parameters:

format - the format of the message to log

args - the arguments of the message to log

d

public static void d(java.lang.String msg)

Log a message with level LogLevel.DEBUG.

Parameters:

msg - the message to log

d

public static void d(java.lang.String msg,
                     java.lang.Throwable tr)

Log a message and a throwable with level LogLevel.DEBUG.

Parameters:

msg - the message to log

tr - the throwable to be log

i

public static void i(java.lang.Object object)

Log an object with level LogLevel.INFO.

Parameters:

object - the object to log

Since:

1.1.0

See Also:

LogConfiguration.Builder.addObjectFormatter(Class, ObjectFormatter)

i

public static void i(java.lang.Object[] array)

Log an array with level LogLevel.INFO.

Parameters:

array - the array to log

i

public static void i(java.lang.String format,
                     java.lang.Object... args)

Log a message with level LogLevel.INFO.

Parameters:

format - the format of the message to log

args - the arguments of the message to log

i

public static void i(java.lang.String msg)

Log a message with level LogLevel.INFO.

Parameters:

msg - the message to log

i

public static void i(java.lang.String msg,
                     java.lang.Throwable tr)

Log a message and a throwable with level LogLevel.INFO.

Parameters:

msg - the message to log

tr - the throwable to be log

w

public static void w(java.lang.Object object)

Log an object with level LogLevel.WARN.

Parameters:

object - the object to log

Since:

1.1.0

See Also:

LogConfiguration.Builder.addObjectFormatter(Class, ObjectFormatter)

w

public static void w(java.lang.Object[] array)

Log an array with level LogLevel.WARN.

Parameters:

array - the array to log

w

public static void w(java.lang.String format,
                     java.lang.Object... args)

Log a message with level LogLevel.WARN.

Parameters:

format - the format of the message to log

args - the arguments of the message to log

w

public static void w(java.lang.String msg)

Log a message with level LogLevel.WARN.

Parameters:

msg - the message to log

w

public static void w(java.lang.String msg,
                     java.lang.Throwable tr)

Log a message and a throwable with level LogLevel.WARN.

Parameters:

msg - the message to log

tr - the throwable to be log

e

public static void e(java.lang.Object object)

Log an object with level LogLevel.ERROR.

Parameters:

object - the object to log

Since:

1.1.0

See Also:

LogConfiguration.Builder.addObjectFormatter(Class, ObjectFormatter)

e

public static void e(java.lang.Object[] array)

Log an array with level LogLevel.ERROR.

Parameters:

array - the array to log

e

public static void e(java.lang.String format,
                     java.lang.Object... args)

Log a message with level LogLevel.ERROR.

Parameters:

format - the format of the message to log

args - the arguments of the message to log

e

public static void e(java.lang.String msg)

Log a message with level LogLevel.ERROR.

Parameters:

msg - the message to log

e

public static void e(java.lang.String msg,
                     java.lang.Throwable tr)

Log a message and a throwable with level LogLevel.ERROR.

Parameters:

msg - the message to log

tr - the throwable to be log

log

public static void log(int logLevel,
                       java.lang.Object object)

Log an object with specific log level.

Parameters:

logLevel - the specific log level

object - the object to log

Since:

1.4.0

See Also:

LogConfiguration.Builder.addObjectFormatter(Class, ObjectFormatter)

log

public static void log(int logLevel,
                       java.lang.Object[] array)

Log an array with specific log level.

Parameters:

logLevel - the specific log level

array - the array to log

Since:

1.4.0

log

public static void log(int logLevel,
                       java.lang.String format,
                       java.lang.Object... args)

Log a message with specific log level.

Parameters:

logLevel - the specific log level

format - the format of the message to log

args - the arguments of the message to log

Since:

1.4.0

log

public static void log(int logLevel,
                       java.lang.String msg)

Log a message with specific log level.

Parameters:

logLevel - the specific log level

msg - the message to log

Since:

1.4.0

log

public static void log(int logLevel,
                       java.lang.String msg,
                       java.lang.Throwable tr)

Log a message and a throwable with specific log level.

Parameters:

logLevel - the specific log level

msg - the message to log

tr - the throwable to be log

Since:

1.4.0

json

public static void json(java.lang.String json)

Log a JSON string, with level LogLevel.DEBUG by default.

Parameters:

json - the JSON string to log

xml

public static void xml(java.lang.String xml)

Log a XML string, with level LogLevel.DEBUG by default.

Parameters:

xml - the XML string to log