13.1. Creating Properties

You want to add properties for color and comments to the Favorites product. The Color property will determine the color used to display an item in the Favorites view, while the comment property will be displayed as an item's hover help.

Since properties are associated with objects, you must decide which type of object will contain properties. The Color property will be added to Favorites items; when an item is removed from the Favorites view, the Color property will be discarded. Conversely, you want the comment property to be associated with the resource behind the Favorites items so that when the resource is removed and then added to the Favorites view, the comment property will be preserved.

13.1.1. FavoriteItem properties

A property can be associated with an object in many different ways, but typically, a property value is accessed through get and set methods on the object itself. For Favorites items, accessor methods need to be added to the IFavoriteItem interface for the new Color property:

Color getColor();
void setColor(Color color);

Because this property is to be implemented identically across all Favorites items, you will place this behavior into a new abstract superclass called BasicFavoriteItem, which all your other item types will extend.

package com.qualityeclipse.favorites.model;

import ...

public class BasicFavoriteItem
{
   private Color color;

   public Color getColor() {
      if (color == null)
         return getDefaultColor();
      return color;
   }

   public void setColor(Color color) {
      this.color = color;
   }

   public static Color getDefaultColor() {
      if (defaultColor == null)
         defaultColor = getColor(new RGB(0, 0, 0));
      return defaultColor;
   }

   public static void setDefaultColor(Color color) {
      defaultColor = color;
   }
}

There are two types of properties: persistent and session. Persistent properties are preserved across multiple workbench sessions, while session property values are discarded when Eclipse exits. To persist the Color property across multiple sessions, you would need to modify the loading and saving methods outlined in Section 7.5.2, Saving global view information, on page 311. This is left as an exercise for the reader, and for now, the Color property will not be preserved across sessions.

A Color object has an underlying OS resource and must be managed properly. Add the BasicFavoriteItem utility methods to cache, reuse, and dispose of colors:

private static final Map colorCache = new HashMap();
private static Color defaultColor;

public static Color getColor(RGB rgb) {
   Color color = (Color) colorCache.get(rgb);
   if (color == null) {
      Display display = Display.getCurrent();
      color = new Color(display, rgb);
      colorCache.put(rgb, color);
   }
   return color;
}

public static void disposeColors() {
   Iterator iter = colorCache.values().iterator();
   while (iter.hasNext())
      ((Color) iter.next()).dispose();
   colorCache.clear();
}

When the Favorites plug-in shuts down, you must clean up any Color objects that you have been managing. Add the following line to the FavoritesPlugin.stop() method:

BasicFavoriteItem.disposeColors();

13.1.2. Resource properties

Eclipse has a generic mechanism for associating properties with resources that you can use to store resource comments. Methods in IResource provide both session properties, which are discarded when Eclipse exits, and persistent properties, which are preserved across multiple workspace sessions. Both types of properties can be used to determine whether an action should be visible (see Section 6.3.2.3, The filter element, on page 230).

getPersistentProperty(QualifiedName) Returns the value of the persistent property of the resource identified by the given key, or null if this resource has no such property. These properties are preserved across different sessions.

getSessionProperty(QualifiedName) Returns the value of the session property of the resource identified by the given key, or null if this resource has no such property. These properties are discarded when Eclipse exits.

setPersistentProperty(QualifiedName, String) Sets the value of the persistent property of the resource identified by the given key. If the supplied value is null, the persistent property is removed from the resource. These properties are preserved across different sessions.

setSessionProperty(QualifiedName, Object) Sets the value of the session property of the resource identified by the given key. If the supplied value is null, the session property is removed from the resource.

The QualifiedName argument in these methods is the key used to store and retrieve a property value. By convention, a key is composed of the plug-in identifier and a string identifying a property within the plug-in. For the Favorites product, define a constant key for the comment property in the BasicFavoriteItem class:

public static final QualifiedName COMMENT_PROPKEY =
   new QualifiedName(FavoritesPlugin.ID, "comment");

As discussed earlier, there are two types of properties: persistent and session. Persistent properties are preserved across multiple workbench sessions, while session property values are discarded when Eclipse exits. You want the comment property to persist across multiple workbench sessions, so use the getPersistentProperty() and setPersistentProperty() methods like this:

String comment =
   resource.getPersistentProperty(
      BasicFavoriteItem.COMMENT_PROPKEY);

   resource.setPersistentProperty(
      BasicFavoriteItem.COMMENT_PROPKEY,
      comment);

If a resource object does not have a Favorites comment associated with it, then you want to display a default comment. Add BasicFavoriteItem utility methods to access the default comment.

public static final String COMMENT_PREFKEY = "defaultComment";

public static String getDefaultComment() {
   return FavoritesPlugin.getDefault().getPluginPreferences()
      .getString(COMMENT_PREFKEY);
}

public static void setDefaultComment(String comment) {
   FavoritesPlugin.getDefault().getPluginPreferences()
      .setValue(COMMENT_PREFKEY, comment);
}