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.

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.

To use the event logger, you should invoke one of the register methods with your applications 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 logEvent methods to log events in the system's event log.

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 ALWAYS_LOG event level.

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

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	getInt(byte[] data) Transmogrify a byte array into an integer.
static int	getMinimumLevel() Retrieves the current minimum logging level.
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 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 value) Logs an ALWAYS_LOG level numeric event for an application.
static boolean	logEvent(long guid, int 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	setMinimumLevel(int level) Sets the new minimum level for logging.

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.

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.

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.

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 VIEWER_NUMBER, VIEWER_STRING, VIEWER_EXCEPTION).

viewer - Application specific event viewer for this application (if any).

Returns:

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

Since:

JDE 3.6

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 VIEWER_NUMBER type for displaying events.

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.

Since:

JDE 3.6

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 VIEWER_NUMBER, VIEWER_STRING, VIEWER_EXCEPTION.

Since:

JDE 3.6

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.

Since:

JDE 3.6

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 register methods).

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).

Since:

JDE 3.6

logEvent

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

Logs an ALWAYS_LOG level event for an application.

The invoker must provide an already-registered GUID (with one of the register methods).

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).

Since:

JDE 3.6

logEvent

public static final boolean logEvent(long guid,
                                     int value,
                                     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 register methods).

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:

JDE 3.6

logEvent

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

Logs an 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 register methods).

Parameters:

guid - GUID of the application logging the event.

value - Numeric value of the event.

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).

Since:

JDE 3.6

getMinimumLevel

public static final int getMinimumLevel()

Retrieves the current minimum logging level.

Returns:

Current minimum logging level.

setMinimumLevel

public static final void setMinimumLevel(int level)

Sets the new minimum level for logging.

Parameters:

level - New minimum logging level.

Since:

JDE 3.6

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.

Since:

JDE 3.6