|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--net.rim.device.api.system.EventLogger
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 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
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
logEvent(long, byte[], int)
to log events for that application.
The logEvent(long, byte[], int)
method can get passed an integer or a long integer
if you are using a VIEWER_NUMBER
viewer type for your application or
a byte array if you are using a VIEWER_STRING
or
VIEWER_EXCEPTION
viewer type.
For example, to pass a String to logEvent(long, byte[], int)
, convert it to a byte
array using the String class' getBytes() function:
EventLogger.register(myApp, 0x4c9d3452d87922f2L, 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
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.
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 );
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 |
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 |
setMinimumLevel(int level)
Sets the new minimum level for logging. |
|
static boolean |
startEventLogViewer()
Starts the event log viewer. |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final long SYSTEM_LOG_GUID
Used for text messages.
public static final int VIEWER_EXCEPTION
Method Detail |
public static int getInt(byte[] data)
data
- Byte array to transmogrify.public static final int getMinimumLevel()
public static final String getRegisteredAppName(long forGUID)
forGUID
- GUID of the registered application.public static final int getRegisteredViewerType(long forGUID)
forGUID
- GUID of registered application.VIEWER_NUMBER
, VIEWER_STRING
, VIEWER_EXCEPTION
.public static final boolean logEvent(long guid, byte[] data)
ALWAYS_LOG
level event for an application.
The invoker must provide an already-registered GUID (with one of the
register(long, java.lang.String, int)
methods).
This method is recommended for use with GUIDs registered as viewer
types VIEWER_STRING
and VIEWER_EXCEPTION
. The data to
be logged must be a byte[].
guid
- GUID of the application logging the event.data
- Data to log.public static final boolean logEvent(long guid, byte[] data, int level)
The invoker must provide an already-registered GUID (with one of the
register(long, java.lang.String, int)
methods).
This method is recommended for use with GUIDs registered as viewer
types VIEWER_STRING
and VIEWER_EXCEPTION
. The data to
be logged must be a byte[].
guid
- GUID of the application logging the event.data
- Data to log.level
- Level for this event.public static final boolean logEvent(long guid, int value)
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(long, java.lang.String, int)
methods).
This method is recommended for use with GUIDs registered as viewer
type VIEWER_NUMBER
.
guid
- GUID of the application logging the event.value
- Numeric value of the event.public static final boolean logEvent(long guid, int value, int level)
The event in this case is always some integer value.
The invoker must provide an already-registered GUID (with one of the
register(long, java.lang.String, int)
methods).
This method is recommended for use with GUIDs registered as viewer
type VIEWER_NUMBER
.
guid
- GUID of the application logging the event.value
- Numeric value of the event.level
- Level for this event.public static final boolean logEvent(long guid, long value, int level)
The event in this case is always some long value.
The invoker must provide an already-registered GUID (with one of the
register(long, java.lang.String, int)
methods).
This method is recommended for use with GUIDs registered as viewer
type VIEWER_NUMBER
.
guid
- GUID of the application logging the event.value
- Numeric value of the event.level
- Level for this event.public static final boolean register(long guid, String name)
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.
If a name/GUID has already been registered with a viewer type other
than VIEWER_NUMBER
, calling this method replaces it with the
VIEWER_NUMBER
type..
guid
- GUID of the registering application.name
- Name of the registering application.public static final boolean register(long guid, String name, int viewerType)
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.
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
).public static final void setMinimumLevel(int level)
level
- New minimum logging level.public static boolean startEventLogViewer()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.