logging4bb

logging4bb – a logging framework for BlackBerry OS 6 and OS 7

What do you need

GIT source repositories:

You also need to install Lilith the LogMonitor from here. (0.9.4.1 or 0.9.4.2 snapshots are good)

Your devices should support

  • OS 6 as minimum
  • SD Cards
  • BIS-B dataplan

If you need it for older OS, without SD or without BIS: fork it and change it, the license allows this

Overview

logging4bb is a background app and will be started automatically.
logging4bb logs events to a remote socket logger (Lilith)
and/or to a local SQLite database.

the goal of this project is to have an easy to use logging framework.

logging4bb is easy to use: run the logger as a system module in the background. logging4bb registers some remote commands.

this enables you to use the logger from as many BlackBerry Apps as you like.

you only have to copy 5 classes into your application…

… change same parameters in the LoggerFactory (marked as TODO) and it works.

the logging from BlackBerry OS Applications works similar to Logging in Java SE:

each class gets a logger:

// the logger
 private static final ILogger logger = LoggerFactory.getLogger(HelloLoggingApp.class);

and you can log as usual:

logger.debug("HelloLoggerScreen successfully initialized");

if the background app isn’t installed on the BlackBerry there’s a fallback to sys-out logging. So its possible only to install the logger if you need it or while testing.

please take a look at my presentation at BlackBerry DevCon 2011 in San Francisco:

Download the pdf: Logging: Esay and Flexible

Hint: you can access all sessions on demand from BlackBerry DevCon here.

OSS as GIT repository at Bitbucket

Why do we prefer Bitbucket ? We also need some private Repositories and Bitbucket allows unlimited for free.

Also Bitbucket supports hg (Mercurial) and git and because we also have some hg repositories Bitbucket is a single place where we can store all.

Branches

logging4bb uses Git to manage different platforms in one single repository.
so the master in this case only has a readme

please checkout the branch you need:

  • dev-public is always the newest one – at the moment BB OS 7
  • os6/dev-public is based on BB OS 6

please take a look at this blog I wrote about Git and mobile development describing the structure of our GIT repositories to understand it.

BIS Connection

logging4bb isn’t running out of the box, because we’re using BIS.
RIM doesn’t allow us to publish the connection string, so you have to edit this.
inside Logging4BBApp the connection string is “????????????” – please replace this with the BIS connection string.
best is to create a local branch for this.
if you don’t have BIS, then you can also use deviceside=true for a direct socket connection – but we only support the BIS version out of the box because all our Apps run on BIS.
BlackBerry Forums will help if you have questions about BlackBerry Connections.

License

We’re using the Eclipse Public License (EPL) for OSS projects. EPL lets you much freedom and can be combined easy with Apache Licenses used by BlackBerry OSS projects at Github.

All documentation and content is licensed under Creative Commons License 3.0 (BY-NC-SA).

Lilith is dual-licensed for Apache 2.0, LGPL and GPL – so its always compatible.

HowTo start easy

There are two ways to get the sources:

  1. download prepared Eclipse Projects
  2. or clone from GIT Repositories

Download the projects

The fastest way to start is to download the Eclipse projects:

then go to your Eclipse and Import | General | Existing Projects into Workspace:

select the archive:

and you’re done.

Don’t forget to change the BIS Connection String in Logging4BBApp:

 // TODO you have to replace this
 private static String SEEKRET_CONNECTION = "??????????????????????????";

you also have to set the HOST IP where Lilith is installed:

 // TODO configure your host address
 // the IP where your Lilith is listening for LogEvents
 private static String HOST_ADDRESS = "127.0.0.1";

and set if you like to log to the server (Lilith) and/or Database (SQLite):

 // TODO set this to true if you like to log to SQLite on your BB
 private static boolean LOG_TO_DB = false;
 // TODO as default we log to Lilith Logmonitor using socket connection
 private static boolean LOG_TO_LOGMONITOR = true;

If launching logging4bb together with the example project don’t forget to start MDS with the simulator and to simulate a SD Card.

Then you should find the example app:

providing some methods to test the logging:

Hint: logging4bb is a system module automatically running in the background without an icon on your homescreen.

Clone the GIT Repositories

You can clone the repositories using HTTPS as read-only Repository:

 git clone https://bitbucket.org/ekkescorner/logger4bb.git
 git clone https://bitbucket.org/ekkescorner/hello-logging4bb.git

Checkout the branch you need into your workspace, per ex. os6/dev-public.

Use the tool you like: the commandline, EGit or (on OSX) Tower.

Here’s the Repository View from EGit:

and here’s Tower on OSX:

Checkout the branch and import project into your workaspace.

Logging to Server (Lilith Logmonitor)

Please download Lilith from Sourceforge:

Lilith is available as APP for OSX and also for Windows and Linux.

Doubleclick to install – if Lilith is running you can send Log Events through Socket Connection Port 10020 (compressed XML)

Originally Lilith is used as a LogMonitor for SLF4J / LogBack. But as you probably know LogBack doesn’t run on BlackBerry OS.

logging4bb uses a trick and sends Log Messages in the same format to Lilith as this would be done using an Appender for Lilith from Java SE applications.

What’s really great if you’re testing Client / Server applications – you can monitor the Logging using Lilith and watch server-logs side-by-side with logs from BlackBerry devices or Simulator.

Lilith isn’t a real Server: you don’t get back any acknowledges – you only send out a stream to the socket connection. Then it depends from the transport protocol if you know if Lilith is really waiting for events: using a direct TCP connection, you’ll get feedback that the connection is closed. To avoid that Lilith thinks your Connection is closed, we’ve implemented a heartbeat protocol sending a Ping Logmessage to Lilith. This is an empty Log Message without a timestamp – so Lilith ignores it but stays live.

Logging to DB (local SQLite)

logging4bb uses a local SQLite database for two use-cases:

  • storing preferences
  • storing log messages

If you’re starting logging4bb the first time, the SQLite will be created automatically ind the preferences will be initialized from the values stored in your Logging4BBApp.

You can change the stored preferences using a tool to manage the SQLite or using a remote command. there are examples in the hello-logging4bb project how to change some values, so it’s possible to change the behaviour if logging should be stopped or go into DB or to Lilith or both.

If logging4bb was started and a DB already exists, then the stored preferences are used instead of the Constants of Logging4BBApp.

Table for preferences:

Table for LogEvents:

some log events stored into SQLite (opened with Firefox PlugIn SQLite Manager):

Hint: if storing events into the local SQLite DB it’s up to you to manage the DB: copy to desktop or delete if not used anymore.

The upcoming Logging4bb Manager will provide a UI and tools for this.

Product: Logging4bb Manager

If you don’t want to build and deploy your own logging4bb APP or you don’t have access to a BIS Connection String, soon there will be the app available from AppWorld as a product using BIS.

Also it will be bundled with a LogManager APP providing a UI to manage the Logging DB preferences or to take a look at the logged events from SQLite DB.

Problems ? Questions ?

please open an issue at Bitbucket here
—————————————————————————————————————————

(c) 2012 Creative Commons License 3.0 (BY-NC-SA) by  ekkescorner 


You must be logged in to post a comment.

%d bloggers like this: