Lotusphere 2009: Preferences in SWT components

On the demos I have done for my Lotusphere 2009 session is a demo on how to use the extension point to extend the preferences dialog box (File/Preferences…) in Notes 8. As always a demo makes it easier to comprehend so download and explore to your heart’s content. Questions are welcome here or at Lotusphere.

com.ls09.bp106.prefs

Otherwise I recommend the Eclipse User Settings FAQ

SWT @ Notes 8: Network awareness from SWT components

One of the big strengths of having Notes 8 built in Lotus Expeditor is that you have access to all the functionality of the underlying Expeditor platform including its services. On if the nice ones is that you can be notified when the underlying network connectivity is available and/or unavailable.

SWT@Notes 8: Workbench startup and the Accounts API

So one of the things I have been wresteling with over the last couple of weeks is the Accounts API in Notes 8 / Expeditor. While very nice at the core it does leave something to be desired. Trying to interact with the Accounts API from a plugin running in Notes can and probably will result in an exception and the following messages being printed to the OSGi console if you happen to be looking there (which you really should). Look for an upcoming post for any easier approach… 🙂

CLFMW0050E: Workbench is not ready to handle
   background thread request !
CLFMW0036E: Workbench is not ready for this
   operation

Suffice it to say that the lesson is that the Accounts API might be the same across Expeditor based clients but the implementation differs. For instance On Notes the accounts are stored in the local name and address book while it is stored in other formats in other Expeditor clients. This is all well and good but the fact that a Notes database is the backend store on Notes leaks through the API. The above messages are solved by running the code that access the Accounts API in a NotesJob. Really!? This is very poor design IMHO but something I think we have to live with.

Ahh the frustrations sometimes makes me want to scream…

SWT@Notes 8: Logging from SWT components

As you probably know using System.out.println for logging in Java is a no-no and this is also the case when developing plugins for Notes 8 and Lotus Expeditor. This post outlines how to use the logging framework supplied with Lotus Expeditor, how to manage the logging and where the logs go.

You have probably been using log4j or similar logging framework for years. Avoiding writing to System.out is even more important when writing SWT components and plug-ins for Notes 8 a.k.a. Eclipse since the output goes to a log tucked away under the covers. Luckily there’s an approach which is so much better and more flexible.

Logging basics

Luckily logging has been built into the language (since Java 1.4) and into the Lotus Expeditor platform. Actually there is 5 different frameworks built into the Lotus Expeditor platform. Based on advise from the Lotus and personal experience I really recommend you use the java.util.logging framework built into the core Java language. This is also known as JSR47 loggers. The below graphics shows the logging sub-system of Lotus Expeditor.



Page 8 from the
IBM Lotus Expeditor 6.1 Client for Desktop Serviceability – Logging and IBM Support Assistant (PDF).

As you can see from the above you can use the following logging frameworks in Lotus Expeditor:

  • Eclipse Logging
  • OSGi Logging
  • IBM Commons Logging
  • Apache Jakarta Commons Logging
  • java.util.logging a.k.a. JSR47

I haven’t got experience with all of the these frameworks and luckily I don’t have to. I just have to know about java.util.logging and there’s an abundance of info on that on Google. The Sun tutorial might be the best place to start if you’ve never used java.util.logging. All this being equal the frameworks work the same with the only difference being how you obtain loggers and what the different logging levels are called. Log levels are called something different in the different frameworks but slide 7 in the Lotus Expeditor documentation on logging shows the mapping between the different frameworks.

Using loggers in code

Using java.util.logging in code is really easy and consists of 3 steps:

  1. Obtain the logger to use (normally in a static final variable).
  2. Write info to the logger.

The below is an example of using loggers.

package com.example.logging;

import java.util.logging.Logger;

public class MyLoggingClass {
   // logger
   private final Logger log = Logger.getLogger(
      this.getClass().getPackage().getName());

   public MyLoggingClass() {
      log.finest("Finest...");
      log.finer("Finer...");
      log.fine("Fine...");
      log.info("Info...");
      log.warning("Warning...");
      log.severe("Severe...");
   }
}

The above code creates a logger in a variable called “log” as a private variable. The logger itself is called com.example.logging which is the name used to control the log level (see below). I find it best to name the logger after the package name that contains the class. Sometimes it is however beneficial to also have a logger with more specialized names to log info on specific events.

Configuring the logger log levels

The log level for a single logger or multiple loggers can be controlled using the LogManager using the <Notes data directory>/workspace/.config/rcpinstall.properties file. To change the log level for the com.example.logging logger to FINEST add the following line to the file and restart the client:

com.example.logging.level=FINEST

To change the level dynamically use the OSGi console commands as described below.

Interacting with loggers from the OSGi console

If you start the Notes 8 client with the OSGi console visible you can interact directly with the loggers using the console command called setlogrlev. To set the log level for the com.example.logging logger to FINEST use the following command:

setlogrlev com.example.logging FINEST

Please note that the logger levels are case sensitive so you have to write “FINEST” and not “finest”.

Where the logging goes

All log messages are written to log files in the <Notes data directory>/workspace/logs directory. Opening the directory will reveal a number of files. The two most important are error-log-X.xml and trace-log-X.xml. The file names are quite explanatory and are, as the extension implies, XML-files. When you open them they’ll be rendered using a XSLT stylesheet to be displayed nicely. You can either read them using a browser or using the “Help/Support/View Log” and “Help/Support/View Trace” menu item in the Notes 8 client.

While the log files are usable I personally find it much easier and better to use the OSGi console when developing as I can adjust the log levels on the fly.

Further reading

SWT @ Notes 8: Why OSGi is important

I have posted stuff on the OSGi console previously and why it’s important but even better is to see for your self. I did this myself by adding TwitNotes console commands to the TwitNotes plugin for version 1.0.4. For the normal user it wont matter but it actually proves to be very useful for troubleshooting and something I will definitely add to the other sidebar projects I’m working on.

For more info and code example see the post “Extending the OSGI Console” by Bob Balfe.

SWT@Notes 8: -console

As partly addressed by Bob Balfe there are numerous ways to debug Eclipse/SWT components in Notes 8 or Lotus Expeditor. One is as Bob mentions to launch the client using the -console switch so the OSGi console is displayed. While confusing at first the OSGi console is really your friend when developing applications. From the console you have direct access to the OSGi subsystem of Eclipse. But it isn’t just for the Eclipse stuff. Since some Notes 8 components such as the property broker and topology manager have console commands you can interact with them from the console when troubleshooting/debugging.

To launch Notes 8 with the OSGi console create a new shortcut and use the following command (change the path if Notes isn’t installed in c:notes8):

"c:notes8frameworkrcprcplauncher.exe" -config notes -console

Besides the -console switch the the rcplauncher.exe executable takes a number of interesting arguments. One of the really cool ones is that you can supply a port number after the -console switch to make the console listen on a telnet port. This way you can connect to a remote client using telnet.

"c:notes8frameworkrcprcplauncher.exe" -config notes -console 23

Cool, cool, cool.

If you’re developing Eclipse components I really suggest you look into the OSGi console as it can assist in troubleshooting bundles that fail to load due to unsatisfied requirements.

Were to start? Well when you have the console available try out these commands:

  • help: Pretty self-explanatory
  • ss: Shows all the bundles installed with their status (be aware – there’s a lot of them)
  • setlogrlev: Sets the log level of individual loggers. I’ll have an upcoming blog post on logging.
  • pbsh: Work with the property broker e.g. see defined wires etc.

SWT @ Notes 8: Here we go again

As mentioned before Lotusphere 2008 I’m contemplating a series of posts on tips and tricks on developing Eclipse/SWT components for Notes 8. I has been a little quiet on this front since Lotusphere since it takes a little more time than I have been having lately to write these posts. Now with Easter on the horizon I’m planning to get a number of posts out there. I’m working on a number of posts on the subject and currently planning to address:

  • Logging
  • Debugging
  • Why OSGi is important
  • Preferences
  • Actions and ViewParts
  • OSGi services vs. Eclipse extensions

If you have other suggestions please let me know by commenting to this post.