net.rim.device.api.system
Class EventLogger

java.lang.Object
  net.rim.device.api.system.EventLogger

public final class EventLogger
extends Object

Logs events into the persistent store.

The event logger stores a sequence of bytes. What those bytes "mean" is determined by the viewer registered to view them. So, for instance, you can log an integer (four bytes) and register a string viewer: those four bytes will then be interpreted as four ASCII characters and displayed as such.

Events are persistent across reset. The device maintains an event queue; when the log gets too full, new events push old ones out of the front of the queue. Approximately 16 K of data can be logged until the log gets too full.

To use the event logger, you should invoke one of the EventLogger.register(long, java.lang.String, int) methods with your application's GUID to register your application to log events. The GUID can be created in the IDE by right-clicking a String, and selecting "Convert String to Long". You can then use the various EventLogger.logEvent(long, byte[], int) methods to log events in the system's event log. You can use any of the logEvent methods as appropriate to the event data to log; it doesn't need to be the same type as your intended viewer type: the logger stores all data as a simple sequence of bytes in any event.

After registering your application, you can make calls to the EventLogger.logEvent(long, byte[], int) to log events for that application. The EventLogger.logEvent(long, byte[], int) method can get passed an integer or a long integer if you are using a EventLogger.VIEWER_NUMBER viewer type for your application or a byte array if you are using a EventLogger.VIEWER_STRING or EventLogger.VIEWER_EXCEPTION viewer type.

For example, to pass a String to EventLogger.logEvent(long, byte[]), convert it to a byte array using the String class' getBytes() function:

   EventLogger.register(0x4c9d3452d87922f2L, "myApp", EventLogger.VIEWER_STRING);

   String logMessage = "An event has been logged.";

   if ( EventLogger.logEvent( 0x4c9d3452d87922f2L, logMessage.getBytes() ) ) {
       System.out.println("Log Successful!");
   }
 

Any time you catch a Throwable object, a message is automatically logged.

To be written into the log, each posted event must either have an event level equal to or lower then the current cut off point or be logged with the EventLogger.ALWAYS_LOG event level.

The default cut off point is EventLogger.WARNING. That is, by default, only events logged with EventLogger.WARNING, EventLogger.ERROR, EventLogger.SEVERE_ERROR, or EventLogger.ALWAYS_LOG are actually written in the log.

The log itself is 16 KB in size; each log entry uses 15 bytes for overhead, plus whatever space is used by the entry's actual data. Once the log meets or exceeds the 16 KB size, old entries will get erased as required to fit in the new entries.

To view the current event log for the device, hold down the ALT key and type "lglg".

Examples
To log a string, you can use code like this:

     EventLogger.logEvent( GUID, yourString.getBytes(), level );
 

The following example demonstrates how to log a numeric event:

 // Register application for event logging.
 EventLogger.register(0x9c805919833654d6L, SampleApp);

 // Set minimum logging level for the event logger.
 EventLogger.setMinimumLevel(EventLogger.INFORMATION, 0x9c805919833654d6L);

 // Log a numeric event.
 EventLogger.logEvent(0x9c805919833654d6L, 12, EventLogger.INFORMATION);
 

Field Summary
static int	ALWAYS_LOG Always log event, regardless of severity.
static int	DEBUG_INFO Debug information level event.
static int	ERROR Error level event.
static int	INFORMATION Information level event.
static int	SEVERE_ERROR Severe level event.
static long	SYSTEM_LOG_GUID System event log GUID.
static int	VIEWER_EXCEPTION Exception event viewer.
static int	VIEWER_NUMBER Number event viewer.
static int	VIEWER_STRING String event viewer.
static int	WARNING Warning level event.

Method Summary
static void	clearLog() Clears the EventLog of all events.
static int	getEffectiveMinimumLevel(long guid) Retrieves the current effective minimum logging level for the event logger with the given GUID.
static int	getInt(byte[] data) Transmogrify a byte array into an integer.
static int	getMinimumLevel() Retrieves the current global minimum logging level.
static int	getMinimumLevel(long guid) Retrieves the current minimum logging level for the event logger with the given GUID.
static String	getRegisteredAppName(long forGUID) Retrieves name of application given GUID.
static int	getRegisteredViewerType(long forGUID) Retrieves the viewer type registered for an application given GUID.
static boolean	logEvent(long guid, byte[] data) Logs an EventLogger.ALWAYS_LOG level event for an application.
static boolean	logEvent(long guid, byte[] data, int level) Logs an event for an application.
static boolean	logEvent(long guid, int code) Logs an EventLogger.ALWAYS_LOG level numeric event for an application.
static boolean	logEvent(long guid, int code, int level) Logs a numeric event for an application.
static boolean	logEvent(long guid, long value, int level) Logs a numeric event for an application.
static boolean	register(long guid, String name) Registers the calling application's name and guid.
static boolean	register(long guid, String name, int viewerType) Registers the calling application's name and GUID, with a particular viewer type.
static void	setGlobalMinimumLevel(int level) Sets the new global minimum level for logging.
static void	setMinimumLevel(int level) Deprecated. Use EventLogger.setMinimumLevel(int, long) instead.
static void	setMinimumLevel(int level, long guid) Sets the new minimum level for logging for the event logger with the given GUID.
static boolean	startEventLogViewer() Starts the event log viewer.
static void	unsetMinimumLevel(long guid) Un-sets the GUID-specific minimum level for logging for the event logger with the given GUID.

Methods inherited from class java.lang.Object

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

Field Detail

SYSTEM_LOG_GUID

public static final long SYSTEM_LOG_GUID

System event log GUID.

Used for text messages.

See Also:

Constant Field Values

DEBUG_INFO

public static final int DEBUG_INFO

Debug information level event.

INFORMATION

public static final int INFORMATION

Information level event.

WARNING

public static final int WARNING

Warning level event.

ERROR

public static final int ERROR

Error level event.

SEVERE_ERROR

public static final int SEVERE_ERROR

Severe level event.

ALWAYS_LOG

public static final int ALWAYS_LOG

Always log event, regardless of severity.

VIEWER_NUMBER

public static final int VIEWER_NUMBER

Number event viewer.

VIEWER_STRING

public static final int VIEWER_STRING

String event viewer.

VIEWER_EXCEPTION

public static final int VIEWER_EXCEPTION

Exception event viewer. This viewer interprets the logged data as the VMs special traceback data to give you a proper stack dump.

Method Detail

register

public static final boolean register(long guid,
                                     String name,
                                     int viewerType)

Registers the calling application's name and GUID, with a particular viewer type.

You must invoke this method before the logger can log events with the given GUID.

If a name/GUID has already been registered with a particular viewer type, calling this method with a new viewer type replaces the previous one.

Parameters:

guid - GUID of the registering application.

name - Name of the registering application.

viewerType - Type of viewer to be used when displaying the event (one of EventLogger.VIEWER_NUMBER, EventLogger.VIEWER_STRING, EventLogger.VIEWER_EXCEPTION).

Returns:

True if the registration was successful. False if another name has already been registered with the specified guid.

register

public static final boolean register(long guid,
                                     String name)

Registers the calling application's name and guid.

You must invoke this method before the logger can log events with the given GUID. This method uses the default EventLogger.VIEWER_NUMBER type for displaying events.

If a name/GUID has already been registered with a viewer type other than EventLogger.VIEWER_NUMBER, calling this method replaces it with the EventLogger.VIEWER_NUMBER type..

Parameters:

guid - GUID of the registering application.

name - Name of the registering application.

Returns:

True if the registration was successful. False if another name has already been registered with the specified guid.

getRegisteredViewerType

public static final int getRegisteredViewerType(long forGUID)

Retrieves the viewer type registered for an application given GUID.

Parameters:

forGUID - GUID of registered application.

Returns:

Viewer type for the registered applicaiton: one of EventLogger.VIEWER_NUMBER, EventLogger.VIEWER_STRING, EventLogger.VIEWER_EXCEPTION.

getRegisteredAppName

public static final String getRegisteredAppName(long forGUID)

Retrieves name of application given GUID.

Parameters:

forGUID - GUID of the registered application.

Returns:

Name for the application with GUID.

logEvent

public static final boolean logEvent(long guid,
                                     byte[] data,
                                     int level)

Logs an event for an application.

The invoker must provide an already-registered GUID (with one of the EventLogger.register(long, java.lang.String, int) methods).

This method is recommended for use with GUIDs registered as viewer types EventLogger.VIEWER_STRING and EventLogger.VIEWER_EXCEPTION. The data to be logged must be a byte[].

Parameters:

guid - GUID of the application logging the event.

data - Data to log.

level - Level for this event.

Returns:

True if event was successfully logged, or if the event does not reach the minimum level for logging; otherwise, false (for example, if the application GUID isn't registered, or the data can't fit in the logger, or the data pointer is null).

logEvent

public static final boolean logEvent(long guid,
                                     byte[] data)

Logs an EventLogger.ALWAYS_LOG level event for an application.

The invoker must provide an already-registered GUID (with one of the EventLogger.register(long, java.lang.String, int) methods).

This method is recommended for use with GUIDs registered as viewer types EventLogger.VIEWER_STRING and EventLogger.VIEWER_EXCEPTION. The data to be logged must be a byte[].

Parameters:

guid - GUID of the application logging the event.

data - Data to log.

Returns:

True if event was successfully logged; otherwise, false (for example, if the application GUID isn't registered, or the data can't fit in the logger, or the data pointer is null).

logEvent

public static final boolean logEvent(long guid,
                                     int code,
                                     int level)

Logs a numeric event for an application.

The event in this case is always some integer value. The invoker must provide an already-registered GUID (with one of the EventLogger.register(long, java.lang.String, int) methods).

This method is recommended for use with GUIDs registered as viewer type EventLogger.VIEWER_NUMBER.

Parameters:

guid - GUID of the application logging the event.

code - a Numeric value representing the event code ( each Byte shifted accordingly ex: ('E'<<24)|('V'<<16)|('C'<<8)|('D')).

level - Level for this event.

Returns:

True if event was logged, or if the event does not reach the minimum level; otherwise, false (if app isn't registered or data can't fit in logger).

logEvent

public static final boolean logEvent(long guid,
                                     long value,
                                     int level)

Logs a numeric event for an application.

The event in this case is always some long value. The invoker must provide an already-registered GUID (with one of the EventLogger.register(long, java.lang.String, int) methods).

This method is recommended for use with GUIDs registered as viewer type EventLogger.VIEWER_NUMBER.

Parameters:

guid - GUID of the application logging the event.

value - Numeric value of the event.

level - Level for this event.

Returns:

True if event was logged, or if the event does not reach the minimum level; otherwise, false (if app isn't registered or data can't fit in logger).

Since:

BlackBerry API 4.0.0

logEvent

public static final boolean logEvent(long guid,
                                     int code)

Logs an EventLogger.ALWAYS_LOG level numeric event for an application.

The event in this case is always some integer value. The invoker must provide an already-registered GUID (with one of the EventLogger.register(long, java.lang.String, int) methods).

This method is recommended for use with GUIDs registered as viewer type EventLogger.VIEWER_NUMBER.

Parameters:

guid - GUID of the application logging the event.

code - a Numeric value representing the event code ( each Byte shifted accordingly ex: ('E'<<24)|('V'<<16)|('C'<<8)|('D')).

Returns:

True if event was successfully logged; otherwise, false (for example, if the application GUID isn't registered, or the data can't fit in the logger).

getMinimumLevel

public static final int getMinimumLevel()

Retrieves the current global minimum logging level.

Returns:

The current minimum global logging level.

See Also:

EventLogger.getEffectiveMinimumLevel(long)

getMinimumLevel

public static final int getMinimumLevel(long guid)

Retrieves the current minimum logging level for the event logger with the given GUID.

Parameters:

guid - The GUID of the event logger whose minimum level to return.

Returns:

The current minimum logging level for the event logger with the given GUID, or -1 if no minimum level is currently set for the given GUID.

See Also:

EventLogger.setMinimumLevel(int, long), EventLogger.getEffectiveMinimumLevel(long)

Since:

BlackBerry API 7.1.0

getEffectiveMinimumLevel

public static final int getEffectiveMinimumLevel(long guid)

Retrieves the current effective minimum logging level for the event logger with the given GUID. This method first checks the minimum level set by EventLogger.setMinimumLevel(int, long) for the given GUID. It then checks the global minimum level returned from EventLogger.getMinimumLevel(). If the per-GUID minimum level has not been set, then the global minimum level is returned. Otherwise, the more verbose of the global and per-GUID minimum levels is returned.

Example 1: Suppose that the global minimum level is INFORMATION and no per-GUID minimum level is set for the given GUID. In this case, INFORMATION will be returned.

Example 2: Suppose that the global minimum level is DEBUG and the per-GUID minimum level is INFORMATION for the given GUID. In this case, DEBUG will be returned.

Example 3: Suppose that the global minimum level is INFORMATION and the per-GUID minimum level is DEBUG for the given GUID. In this case, DEBUG will be returned.

Parameters:

guid - The GUID whose effective minimum logging level to return.

Returns:

The current effective minimum logging level for the event logger with the given GUID.

Since:

BlackBerry API 7.1.0

setGlobalMinimumLevel

public static final void setGlobalMinimumLevel(int level)

Sets the new global minimum level for logging. Note that setting the minimum level to below EventLogger.WARNING drastically increases the number of messages logged to the event log, and may dramatically degrade device performance. If you only want to set the logging verbosity for your own logger, use EventLogger.setMinimumLevel(int, long) instead.

Note: This method contains the logic formerly used by EventLogger.setMinimumLevel(int) before it was changed to only set the minimum level for the GUIDs registered by the calling application.

Parameters:

level - The new minimum logging level.

Throws:

IllegalArgumentException - if the level is not supported; supported levels are EventLogger.DEBUG_INFO, EventLogger.INFORMATION, and EventLogger.WARNING.

Since:

BlackBerry API 7.1.0

setMinimumLevel

public static final void setMinimumLevel(int level)

Deprecated. Use EventLogger.setMinimumLevel(int, long) instead.

Sets the new minimum level for logging for all event loggers registered by the calling application.

Previously, this method used to set the global minimum level, which affected the minimum level of all registered loggers. This, however, caused degraded device performance if set to a level that was too verbose. Therefore, the behavior of this method was changed to only set the minimum level for loggers that were registered by the calling application. Due to the new non-deterministic behavior of this method, it is strongly recommended to use EventLogger.setMinimumLevel(int, long) instead, so that the loggers whose minimum level to affect are explicitly specified.

Parameters:

level - The new minimum logging level; valid values are EventLogger.DEBUG_INFO, EventLogger.INFORMATION, EventLogger.WARNING, EventLogger.ERROR, and EventLogger.SEVERE_ERROR.

Throws:

IllegalArgumentException - if the given value for level is not valid.

SecurityException - if the calling application is denied access to ApplicationPermissions.PERMISSION_DEVICE_SETTINGS permission.

setMinimumLevel

public static final void setMinimumLevel(int level,
                                         long guid)

Sets the new minimum level for logging for the event logger with the given GUID.

If no event logger with the given GUID is currently registered, then the given level will be saved and used as the minimum level for an event logger that is later registered with the given GUID.

Note that the level that is set by this method will not persist across device resets.

For more information on how the per-GUID minimum level is used when determining whether or not to emit log messages to the event log, see EventLogger.getEffectiveMinimumLevel(long).

Parameters:

level - The new minimum logging level; valid values are EventLogger.DEBUG_INFO, EventLogger.INFORMATION, EventLogger.WARNING, EventLogger.ERROR, and EventLogger.SEVERE_ERROR.

guid - The GUID of the event logger whose minimum level to set.

Throws:

IllegalArgumentException - if the given value for level is not valid.

SecurityException - if the calling application is denied access to ApplicationPermissions.PERMISSION_DEVICE_SETTINGS permission.

See Also:

EventLogger.unsetMinimumLevel(long), EventLogger.getMinimumLevel(long)

Since:

BlackBerry API 7.1.0

unsetMinimumLevel

public static final void unsetMinimumLevel(long guid)

Un-sets the GUID-specific minimum level for logging for the event logger with the given GUID.

If no GUID-specific minimum level has been set for the given GUID using EventLogger.setMinimumLevel(int, long), then this method does nothing. Otherwise, the logging level for the event logger with the given GUID will be changed to follow the global minimum level.

For more information on how the per-GUID minimum level is used when determining whether or not to emit log messages to the event log, see EventLogger.getEffectiveMinimumLevel(long).

Parameters:

guid - The GUID of the event logger whose minimum level to unset.

Throws:

SecurityException - if the calling application is denied access to ApplicationPermissions.PERMISSION_DEVICE_SETTINGS permission.

See Also:

EventLogger.setMinimumLevel(int, long), EventLogger.getMinimumLevel(long)

Since:

BlackBerry API 7.1.0

clearLog

public static final void clearLog()

Clears the EventLog of all events.

getInt

public static int getInt(byte[] data)

Transmogrify a byte array into an integer.

Parameters:

data - Byte array to transmogrify.

Returns:

Integer built from specified byte array.

startEventLogViewer

public static boolean startEventLogViewer()

Starts the event log viewer.

Returns:

True If the viewer was successfully started; otherwise, false.

Since:

BlackBerry API 4.0.0