If you do a lot of ORM or EJB remoting, you probably deal with a lot of Serializable classes. And you’re probably used to the annoying warning message that you see all the time in your IDE when you’re working with Serializable classes:

The serializable class BlaBlaBla does not declare a static final serialVersionUID field of type long BlaBlaBla.java myProject/src/main/java/us/mikedesjardins/foo/domain/entity line 44

If you’re like me, you roll your eyes and politely add a @SuppressWarnings(“serial”) to the top of the class definition (or, worse, you just shut the warning message off in your IDE altogether. Even I don’t do that!). You reason with yourself that current versions of Java conveniently and automatically compute the serialVersionUID at run-time, so there’s no need to bother with the formality of a version number on your class – it’s just a nuisance holdover from days of Java yore.

IT’S A TRAP!
Now that I’ve found myself well into a new project with this lazy philosophy, I’m starting to run into problems. I have a client of my EJB that uses one of these Serializable objects, and I’m finding that when I make the most trivial changes to my shared classes, I need to compile both the server and the client components. The two components that were supposed to be loosely coupled are now hopelessly intertwined. So I did some further research on how the JVM computes the ad-hoc serialVersionUID at runtime when it isn’t provided.

This article over at JavaWorld does a far better and more thorough job of explaining it than I will. In a nutshell, backward-compatability with respect to serialization and de-serialization is a lot less fragile than the cases that the serialVersionUID generation is protecting you against. That version generation algorithm computes an SHA hash based on the class name, sorted member variables, modifiers, and interfaces.

In reality, serialization and de-serialization generally only breaks when one of the following things happens to your class (from the aforementioned article at JavaWorld):

• Delete fields
• Change class hierarchy
• Change non-static to static
• Change non-transient to transient
• Change type of a primitive field

Ensure Minimal Coupling Between Components
To ensure that your components which use Serialization have minimal runtime dependencies on each other, you have two options:

• Declare a specific serialVersionUID, and update it whenever you make a change that breaks backward compatability.
• Don’t rely on any classes for use as transfer objects which will potentially change. This one is pretty obvious, but sometimes you will be surprised down the road at which classes are modified more often than others.
• Don’t use your own objects at all when transferring data. Instead, rely on classes like Integers, Strings, or HashMaps to shuttle data around among components. (Obviously, protocols like SOAP and REST rely on XML documents for this to ensure maximum de-coupling, but you’re presumably using something like EJB remoting to avoid the complexity or overhead of these protocols).

Photo Credit: Mike Johnson

I noticed that there weren’t a lot of tutorials out there on the topic of mixing Python with GConf, so I decided to write one.

First, you’ll need to import the Python bindings for GConf:

import gconf

Next, you want to create a GConf “client” in your Python app. You’ll probably want to do this in an __init__() function somewhere. You’ll also want to register your application to receive notifications when ever your configuration values change. The hierarchy of configuration values in GConf follows the familiar slash-separated path notation. For example, the configuration values for my AWN weather applet are stored in /apps/avant-window-navigator/applets/weather. So, if I want to register a callback named config_event to be called whenever configuration values on that path are modified, I’d do the following:

self.gconf_client = gconf.client_get_default()
self.gconf_client.notify_add("/apps/avant-window-navigator/applets/weather", self.config_event)

I usually write a generic “get_config” function, and have the callback call get_config. That way, I can use the same configuration code when I initialize. The config callback then looks simple… something like this:

def config_event(self, gconf_client, *args, **kwargs):
  self.get_config()

The kwargs parameter gives you a list of parameters that changed. You can fine-tune your configuration code based on this, but I usually just ignore it and re-read everything because I don’t usually have very many parameters.

GConf provides functions for reading your parameters. They look like this:

foo = self.gconf_client.get_string("/path/to/my/config/data/foo")
bar = self.gconf_client.get_int("/path/to/my/config/data/bar")
baz = self.gconf_client.get_bool("/path/to/my/config/data/baz")

All of the functions except get_boolreturn None if the key isn’t found. Oddly, get_bool seems to return False if the key isn’t found. In my configuration code, I like to initialize my GConf values when the key isn’t found. So when if my code were to read the “foo” parameter like the above example, it’d actually be coded something like this:

foo = self.gconf_client.get_string("/path/to/my/config/foo")
if foo == None:
  self.gconf_client.set_string("/path/to/my/config/foo", "Default Value")
  foo = "Default Value"

And I usually wrap the above idiom in its own function that accepts a key name and a default value.


Note that you can edit and interact with your GConf settings in realtime using the GNOME configuration tool. If you use Ubuntu, then this utility may be found under the “System Tools” menu. Editing configuration values in the configuration tool will result in your callback being executed as you might expect.

This also makes creating a configuration dialog easy. The configuration dialog just needs to write its updated values to gconf when the user clicks Apply or OK. If you’ve created a callback and generic configuration function, then the application will automatically reconfigure itself after the user applies their modifications!

A while ago, I decided it was time to add some alternate (that is, non-English) language support to the applet. The de-facto standard tool to accomplish this is the Python variant of GNU’s gettext. I found a couple of resources that helped guide me through this. The first was the wiki for the “one laptop per child” project, which does a lot of L10N in Python. The second was an excellent post in the “Learning Python” blog (the author doesn’t give his/her name in the “Who am I” section, otherwise I’d give props). And of course, there’s always the official Python library documentation, too.

The first step is to import the gettext libraries into your Python code, and do some setup work, thusly:

APP="awn-weather-applet"
DIR=os.path.dirname (__file__) + '/locale'
import locale
import gettext
#locale.setlocale(locale.LC_ALL, '')
gettext.bindtextdomain(APP, DIR)
gettext.textdomain(APP)
_ = gettext.gettext

(Note: Made an edit to the above source code on Nov 16 2007 – evidently, the DIR parameter needs the full path to work properly)

Now, here’s what we’re actually doing. The call to bindtextdomain is binding the awn-weather-applet domain to the locale subdirectory. When the applet is deployed, it has a locale directory right underneath the main script, weather.py. The directory argument of bindtextdomain is relative, so we’re pointing gettext at that directory. We’re basically telling gettext to look in the locale subdirectory for files named language/LC_MESSAGES/awn-weather-applet.mo, where language is the two-letter language code defined by the environment (more on that later).

It should be noted that, customarily, locale files are stored in a default location which is a more global place in the filesystem, e.g. /usr/share/locale/language/LC_MESSAGES. If you don’t supply a directory to the bindtextdomain method call, gettext will use the default directory for the system. I opted not to use the default filesystem location because I wanted non-superusers to be able to easily use language files that I supply with the applet, using the standard AWN applet installation mechanism. Requiring the user to put .mo files in the /usr/share directory tree isn’t an option.

The call to textdomain sets the global domain to awn-weather-applet. Essentially we’re telling gettext that all future calls into gettext should use the awn-weather-applet domain as its source for translations.

Lastly, the line that reads _ = gettext.gettext() defines a convenient alias that we will use to identify strings in our code that need translation. If you’re familiar with i18n of C applications, this will look quite familiar; in the C implementation, an identically named macro is used for the same purpose.

The next step is to read through the code to identify the literal strings that will be translated. Generally, any UI element that a user will see is a candidate for translation. Things like log and console output are not as important. When we find a candidate string, we wrap it in _( ). For example, this:

self.dialog.set_title("Forecast")

becomes

self.dialog.set_title(_("Forecast"))

Because of the alias at the top of the source file, what we’re really doing is this:

self.dialog.set_title(gettext.gettext("Forecast"))

It’s a good thing we have the shorthand version!

As I alluded to earlier, gettext does its magic by reading files that ends in an .mo extension. At runtime, it reads the string that’s passed into it (in the above example, “Forecast”), then looks up that string in the proper .mo file to see if a translation is available. If it finds an entry, it returns the translated string, otherwise it just returns the string that was passed into it. So our next task is to create the .mo files.

Creating .mo files is a three step process. First, we need to run a tool that extracts all of the strings to be translated into a usable text file that a translator can edit. The tool to do this is called xgettext. The command line to run looks like this:

xgettext --language=Python --keyword=_ --output=awn-weather-applet.pot *.py

This command generates an output file named awn-weather-applet.pot which acts as a template for translators to do their translation. The file has a bunch of lines that look like this:

#: weather.py:127
msgid "Forecast"
msgstr ""

So, let’s say we want to make a Spanish translation of the weather applet. First, we’d make a copy of this file, and name it something sensible like awn-weather-applet.po (note, you can also use the msginit tool, which does a few other housekeeping things for you like fill in the e-mail address). We’d find all the lines that start with msgid, translate it, and put the result in the following line’s msgstr, like this:

#: weather.py:127
msgid "Forecast"
msgstr "Pronóstico"

Next, we need to “compile” the awn-weather-applet.po file into an awn-weather-applet.mo file, so that it’s usable by gettext at runtime. This is done using the msgfmt command, like this:

msgfmt awn-weather-applet.po -o awn-weather-applet.mo

That’s it! Now all you need to do is ensure that the awn-weather-applet.mo file ends up in the (base of weather applet)/locale/es/LC_MESSAGES directory, and Spanish translations work!

Unfortunately, there’s one small trick you need to work around. If your applet is so simple that it just needs a single, static icon, then sub-classing awn.AppletSimple, followed by a call to set_icon, works great. It gets more difficult if you need to draw dynamic content in the area usually occupied by the icon.

The problem is that set_icon (as well as its misunderstood cousin, set_temp_icon) takes a Pixbuf as its input parameter. However, the drawing framework for doing just about anything, especially loading PNGs, is cairo. Cairo has no native support for converting a surface to a Pixbuf. I discovered a trick for doing this by looking at the source code for the PyClock and BlingSwitcher applets. Let’s say you have a Cairo image surface that you’ve created from an existing PNG, thusly:

cs = cairo.ImageSurface.create_from_png(iconName)
ct = cairo.Context(cs)
ct.set_source_surface(cs)
ct.paint()

…and you want to get a Pixbuf from that image. The following function takes the surface, writes it to a PNG that is stored in a string, then uses the Pixbuf loader to load it from that PNG string:

# Stolen from diogodivision's "BlingSwitcher"
def get_pixbuf_from_surface(self, surface):
  sio = StringIO()
  surface.write_to_png(sio)
  sio.seek(0)
  loader = gtk.gdk.PixbufLoader()
  loader.write(sio.getvalue())
  loader.close()
  return loader.get_pixbuf()

Neat, huh? This is how I manage to display the temperature on the weather applet. I load up the icon into an ImageSurface, write the text on top of it by calling show_text, call the function above to convert the ImageSurface to a PixBuf, then call set_temp_icon using the new PixBuf.

You can see it in action by downloading the weather applet, and looking in weather.py. The relevant code is in the draw_current_conditions function.

In the python script that will be parsing this, you’d want to import the minidom package. Let’s assume that the above XML is served by the URL http://menu.pizzaplace.us, so you’ll want to import urllib as well. The python code to read up the XML Document might look like the following:

from xml.dom import minidom
import urllib
import sys
try:
 usock = urllib.urlopen(‘http://menu.pizzaplace.us’)
 xmldoc = minidom.parse(usock)
 usock.close()
except:
 print “Something really bad happened! “, sys.exc_info()[0]

Easy, right? Now we want to get the actual data out of the Pizza Menu. Everything in your DOM tree is a Node. This includes text between element tags. In fact, in minidom, the whitespace between strings of text is a node, too (more on that in a minute!). To fetch nodes, you use the getElementsByTagName function. This function returns a List of nodes with matching element tag names. Another handy function is getAttribute. As you might expect, it returns the value for an attribute on a particular element.

Let’s say we want to iterate through all of the pizzas on the pizza-menu, printing the type of pizza. That code would look like this:

from xml.dom import minidom
import urllib
try:
 usock = urllib.urlopen(‘http://menu.pizzaplace.us’)
 xmldoc = minidom.parse(usock)
 usock.close()
 pizza_list = xmldoc.getElementsByTagName(‘pizza’)
 for pizza_element in pizza_list:
  pizza_type = pizza_element.getAttribute(‘type’)
  print ‘Pizza Type: %s’ % pizza_type
except:
 print “Something really bad happened! “, sys.exc_info()[0]

Next, let’s pretend that “heart-attack-special” pizza sounds really appetizing, and we want to estimate just how much our cholesterol count will spike if we have a slice. We probably want to iterate over the toppings on that pizza to perform that evaluation. To that end, we will hunt for the pizza with the type “heart-attack-special”, grab that node, then iterate over the topping sub-nodes. Here’s how we would do that:

from xml.dom import minidom
import urllib
try:
 usock = urllib.urlopen(‘http://menu.pizzaplace.us’)
 xmldoc = minidom.parse(usock)
 usock.close()
 pizza_list = xmldoc.getElementsByTagName(‘pizza’)
 for pizza_element in pizza_list:
  pizza_type = pizza_element.getAttribute(‘type’)
  print ‘Pizza Type: %s’ % pizza_type
  if pizza_type == ‘heart-attack-special’:
   topping_list = pizza_element.getElementsByName(‘topping’)
   for topping_element in topping_list:
    # (do something here)
except:
 print “Something really bad happened! “, sys.exc_info()[0]

As you can see, the pizza_element is a node like any other node, so you can call getElementsByName on it to get any child nodes of this pizza element. The toppings (pepperoni, sausage, hamburg, canadian bacon, and ham) are themselves child nodes of their respective elements. Each node has a nodeType property which describes the nature of that node. The nodeTypes are TEXT_NODE, ELEMENT_NODE, ATTRIBUTE_NODE, and DOCUMENT_NODE. Thus, the word “pepperoni” is a child node of the first topping node, and is of type TEXT_NODE.

You might be surprised to learn that the fourth topping node on the heart-attack-special is comprised of three child text nodes. The text “canadian bacon” has a child with the value bacon, a child with a single character of whitespace, and a child with the value bacon. This is not usually how we want to access the data in our XML documents; we’d prefer that “canadian bacon” be treated as a single node comprised of one string.

To make the data behave the way we expect it to, we can introduce our own simple utility method called getText. This function concatenates all child nodes of the supplied node list which are of type TEXT_NODE. It looks like this:

def getText(nodelist):
 rc = “”
 for node in nodelist:
  if node.nodeType == node.TEXT_NODE:
   rc = rc + node.data
 return rc

To use it, we’d pass it the parent node of the text we’re interested in. Going back to our original example, we can use the getText function to print out each topping on our heart-attack-special pizza:

from xml.dom import minidom
import urllib
try:
 usock = urllib.urlopen(‘http://menu.pizzaplace.us’)
 xmldoc = minidom.parse(usock)
 usock.close()
 pizza_list = xmldoc.getElementsByTagName(‘pizza’)
 for pizza_element in pizza_list:
  pizza_type = pizza_element.getAttribute(‘type’)
  print ‘Pizza Type: %s’ % pizza_type
  if pizza_type == ‘heart-attack-special’:
   topping_list = pizza_element.getElementsByName(‘topping’)
   for topping_element in topping_list:
    topping_text = getText(topping_element)
    print ” Topping: %s” % topping_text
except:
 print “Something really bad happened! “, sys.exc_info()[0]

The XML-parsing portions of the weather applet that I wrote for the Avant Window Navigator aren’t much more complicated than this. You can download the source code for the weather applet here. The parts which parse weather.com’s data are in the weather.py script, in the get_conditions and get_forecast functions.

Here’s a screenshot of my dock:

You hear a lot about open source developers who got involved because they needed to “scratch an itch.” I happen to do web development in Java, and I had come to rely on my Gnome CPU Meter applet to tell me when Tomcat had finished deploying (there was always a spike while it was deploying a war file, and then a dropoff when it was finished). I didn’t have that in AWN. Fortunately, you can make applets for it.

So the first applet I created, after a “Hello World” applet and a clock, was a C-based applet called CPU Meter (incidentally, my “Hello World” applet is now part of the awn-extras package). For the CPU Meter, I stole some code from the Gnome System Monitor, mashed it into my Hello World applet, read up on the Cairo Graphics API and GTK+ API, and cobbled together a working CPU load grapher. Later on, another developer came up with an applet called “AwnTop” (a process listing applet), and he merged my stuff in with his stuff. The new applet is now called the AWN System Monitor.

Next, I decided to create a weather applet. All of the other developers had started writing their applets in Python, so I figured it was as good time as any to learn Python! I’ve gotta say I LOVE Python. It’s JavaScript’s simplicity, Shell scripting’s ease-of-use, and Perl’s power… and it’s incredibly easy to read and learn. Here’s a picture of the weather applet in action:

Cool, huh?

Well, I really didn’t intend for this post to be a brag session. I wanted it to be a how-to develop applets for AWN using Python. But now I guess I’ll leave that for the next post!