This isn’t going to be an indictment of bad programming; in fact, I think it’s good if you can look back at your old code and see where it could be improved. Such a process suggests that you are continually self-improving, a skill crucial in software development. Besides, all of us have made a mistake or two at times when we were stressed, tired or just plain not thinking straight.

However, there’s one mistake that I’ve seen that I think warrants bringing to light, and that is the misuse of the Flyweight pattern.

Who wants to be a Flyweight?

Flyweight is typically used to describe one of the smaller weight classes in boxing or other fighting sports. This “minimal” aspect is what is shared with the design pattern of the same name. Simply put, a Flyweight object is one that reduces memory use by sharing common data with other objects. Despite this plain definition, implementing the Flyweight pattern can be tricky.

Perhaps this is why I have seen examples like this: (Java pseudo-code below; may not compile, but you shouldn’t use it anyways)

public class WidgetWithManyFields() {
  private Data field1;
  private String field2;
  private int field3;
  // A lot more fields...
  private SomeOtherData fieldN;

  // Getters and setters...
}

Now, obviously the memory footprint of WidgetWithManyFields can be quite large, and since not all aspects of an application will need access to all data fields, it was decided that a “Flyweight” was needed:

public class WidgetFlyweight() {
  // Only these fields are needed.
  private Data field1;
  private String field2;

  public WidgetFlyweight() {
    // Default constructor.
  }

  // Constructor to make one from the regular widget class.
  public WidgetFlyweight(WidgetWithManyFields widget) {
    this.field1 = widget.getField1();
    this.field2 = widget.getField2();
  }
  // Getters and setters...
}

This isn’t really the Flyweight pattern at all. In fact, I don’t even know if it is a pattern at all. It might be considered something like the Proxy pattern, if the “Flyweight” class contained an instance of the regular class. But I don’t really know.

So what is a Flyweight?

Consider the example of a document that can have images embedded in it. There might be multiple copies of the same image present in the document, but each copy would be sized and positioned differently within the document.

In this case, you wouldn’t want to load and store the data in memory for multiple copies of the same image as that would be wasteful. However, each instance of the image displayed in the document might be formatted or positioned differently. How might this be done?

Firstly, some assumptions:

• An image is uniquely identified by some resource path.
• The underlying image data does not change during the lifetime of the application.

With these assumptions, we can define three classes that allow us to implement the Flyweight pattern.

Firstly, an ImageData class that encapsulates the actual image data. There should be only one canonical instance of this class for each unique resource path. Because of this, we can pool these objects for reuse.

However, the ImageData objects won’t be directly used by other parts of the application. Instead, we create an ImageFlyweight class that is manipulated. Each instance contains a reference to a canonical ImageData object and also stores information about how to format and position the image.

In this way, there can be multiple ImageFlyweight instances that reference the same image and hence the same ImageData instance, but each instance would define separate formatting and positioning details.

Tying everything together is a factory (ImageFlyweightFactory) that maintains the pool and is the access point for getting instances of ImageFlyweight.

Below is the code: (Sorry, it’s a lot of code to throw at you at once, but I didn’t feel like breaking it down into separate chunks, and you can just copy & paste it into your favourite IDE for inspection/compilation)

/**
 * Copyright (c) 2012 Peter Chng, http://unitstep.net/
 */
package net.unitstep.examples.flyweight;

import java.util.HashMap;
import java.util.Map;

/**
 * In order for the Flyweight Pattern to be effective, ImageFlyweight instances
 * should only be obtained via ImageFlyweightFactory.getImageFlyweight().
 *
 * This ensures that for each unique resource path, there is only one instance
 * of the backing ImageData existing in the application.
 *
 * @author Peter Chng
 */
public class ImageFlyweightFactory {
  private Map<String, ImageData> imageDataPool =
      new HashMap<String, ImageData>();

  public ImageFlyweight getImageFlyweight(final String resourcePath) {
    // This will return a new ImageFlyweight object each time; however, the
    // backing ImageData might be shared across multiple ImageFlyweight
    // instances.
    return new ImageFlyweight(this.getImageData(resourcePath));
  }

  private ImageData getImageData(final String resourcePath) {
    ImageData imageData = this.imageDataPool.get(resourcePath);
    if (null == imageData) {
      imageData = new ImageData(resourcePath);
      this.imageDataPool.put(resourcePath, imageData);
    }
    return imageData;
  }

  /**
   * @return the current count of ImageData instances in the pool; only for
   *         testing purposes.
   */
  public int getImageDataPoolCount() {
    return this.imageDataPool.size();
  }

  /**
   * Will contain the data representing an image loaded from some resource, i.e.
   * the file system.
   *
   * This is a private inner class because it should never need to be used
   * externally by callers. It is considered an implementation detail.
   *
   * We assume that the resource path is the uniquely-identifying aspect of an
   * image and that the underlying image resource/data will not change over the
   * lifetime of the application.
   *
   * Thus, only one instance of the ImageData class is needed for each image
   * uniquely identified by its resource path.
   *
   * @author Peter Chng
   */
  private class ImageData {
    private final byte[] data;
    private final String resourcePath;

    public ImageData(final String resourcePath) {
      this.resourcePath = resourcePath;

      // Image data would be loaded here based on the resource path supplied.
      // For brevity, it's not really done.
      this.data = new byte[] {};
    }

    public byte[] getData() {
      // Note: If we really intend to make this class immutable, we should
      // return a defensive copy instead so that callers cannot modify the
      // data stored in this instance.
      return this.data;
    }

    public String getResourcePath() {
      return resourcePath;
    }

    // Note: Not strictly necessary to override equals() and hashCode() for this
    // example, but it's done to indicate we only consider the resource path
    // in determining equality.
    @Override
    public boolean equals(final Object object) {
      if (null == object) {
        return false;
      }
      if (object == this) {
        return true;
      }
      if (object.getClass() != this.getClass()) {
        return false;
      }
      return this.resourcePath.equals(((ImageData) object).getResourcePath());
    }

    @Override
    public int hashCode() {
      return this.resourcePath.hashCode();
    }
  }

  /**
   * The ImageFlyweight object contains a reference to a canonical ImageData
   * object containing the actual image data we wish to render.
   *
   * By making this a static inner class of {@link ImageFlyweightFactory} and
   * the constructor private, instantiation of this class can be controlled and
   * limited to only the {@link ImageFlyweightFactory}. Callers MUST obtain an
   * instance of the ImageFlyweight through the factory and not by direct
   * instantiation.
   *
   * It also contains other properties that will affect the rendering of the
   * image in the application, such as height, width and position.
   *
   * Reusing the same ImageData object across different ImageFlyweight instances
   * allows us to display the same image in different ways within the
   * application, without having to load (or store in memory) the image data
   * multiple times.
   *
   * @author Peter Chng
   */
  public static class ImageFlyweight {
    private final ImageData imageData;

    private int height;
    private int width;
    private int positionX;
    private int positionY;

    private ImageFlyweight(final ImageData imageData) {
      this.imageData = imageData;
    }

    public byte[] getData() {
      return this.imageData.getData();
    }

    // Getters/setters for height, width, positionX, positionY...

    public int getHeight() {
      return height;
    }

    public void setHeight(int height) {
      this.height = height;
    }

    public int getWidth() {
      return width;
    }

    public void setWidth(int width) {
      this.width = width;
    }

    public int getPositionX() {
      return positionX;
    }

    public void setPositionX(int positionX) {
      this.positionX = positionX;
    }

    public int getPositionY() {
      return positionY;
    }

    public void setPositionY(int positionY) {
      this.positionY = positionY;
    }
  }
}

Everything is contained within the ImageFlyweightFactory class, because the ImageData class does not need to be visible to outsiders and callers should not be able to instantiate ImageFlyweight instances on their own.

With this code, we have a simple test harness to verify whether it’s working:

/**
 * Copyright (c) 2012 Peter Chng, http://unitstep.net/
 */
package net.unitstep.examples.flyweight;

import net.unitstep.examples.flyweight.ImageFlyweightFactory.ImageFlyweight;

import org.apache.log4j.Logger;

/**
 * @author Peter Chng
 */
public class ImageFlyweightTest {

  private static final Logger LOGGER =
      Logger.getLogger(ImageFlyweightTest.class);

  public static void main(final String[] args) {
    final ImageFlyweightFactory factory = new ImageFlyweightFactory();

    final String resourcePath1 = "/path/to/images/someImage.png";
    final String resourcePath2 = "/path/to/images/anotherImage.png";

    final ImageFlyweight image1 = factory.getImageFlyweight(resourcePath1);

    displayImageDataCountInPool(factory);

    final ImageFlyweight image2 = factory.getImageFlyweight(resourcePath2);

    displayImageDataCountInPool(factory);

    // Should not create an new ImageData instance in the pool.
    final ImageFlyweight image3 = factory.getImageFlyweight(resourcePath1);

    displayImageDataCountInPool(factory);
  }

  private static void displayImageDataCountInPool(
      final ImageFlyweightFactory factory) {
    LOGGER.debug("Current number of ImageData instances: "
        + factory.getImageDataPoolCount());
  }
}

Running the code yields the following results:

DEBUG ImageFlyweightTest - Current number of ImageData instances: 1
DEBUG ImageFlyweightTest - Current number of ImageData instances: 2
DEBUG ImageFlyweightTest - Current number of ImageData instances: 2

The key point is that after the third ImageFlyweight object is created, the count in the ImageData pool does not increase since the same image has already been “loaded”.

Other examples

Note that Java itself implements something similar to the Flyweight pattern for Strings; this is known as string interning and many other languages support this feature as well.

Basically, because Strings are immutable, Java can store each distinct value in a pool and then reuse these instances when appropriate. As an example, the following code displays “EQUAL”:

String string1 = "A test of the string intern pool.";
String string2 = "A test of the string intern pool.";
// Note that we are comparing object identity, NOT equality.
if (string1 == string2) {
  System.out.println("EQUAL");
} else {
 System.out.println("NOT EQUAL");
}

Note that this doesn’t work if you directly create a String using the new keyword.

Conclusion

I know that this was a fairly contrived example (aren’t they all?), but I hope it provided the basics of the Flyweight pattern to readers. There are a lot of holes and I don’t suggest you directly copy this example for production code, but instead learn the skills to effectively develop the pattern on your own.

As always, I welcome questions or comments and especially corrections if I’ve made a mistake! Thanks for reading!

Mercurial is my distributed revision control system of choice, a trait I picked up at my previous job. I haven’t had the opportunity to deal with Git for any period of time, so I can’t comment on the various “Why X is better than Y” arguments out there.

Most of you using Mercurial/Hg (or revision control in general) will be familiar with the concept of merging, where the changes in a source branch are merged into a target branch, creating a new revision or changeset on the target branch. But what about the times when you would like to combine two or more changesets/revisions into a single one that has the combined/overall changes of all of them? In that case, the Mercurial Queues extension provides for the concept of folding, which accomplishes just that.

Mercurial Queues

The Mercurial Queues extension (mq) is one of the most useful Hg extensions available, as it allows for much more than folding. Basically, mq allows you to import changesets to a patch queue, where they can be manipulated. In this way, previously immutable changesets can be modified. One such modification is the concept of folding, where one more more changesets are combined to produce a single changeset with the equivalent effect.

Proceed with caution

Because mq can directly modify changesets (i.e. revision history), it can have adverse on your Hg repository; data can be permanently lost, since the changes that can be made cannot be “backed out” or “reverted”. I strongly recommend cloning your Hg repo before undertaking any actions with Mercurial Queues for the first time, if only for peace of mind and the fact that cloning is such an easy operation with Mercurial.

The case for folding

Generally, it’s not a good idea to go and change revision history, which is what folding does. The purpose of revision control is to preserve history and provide a timeline for how the codebase has evolved. In the case of Mercurial, it’s especially troublesome to go and modify revision history on a central server that others are pushing to/pulling from, as this may cause inconsistencies. Having said that, there are times when combining multiple changesets into one may be beneficial.

Some examples that come to mind are:

• You have made many intermediate commits to your local Hg repository during development, but would like to combine them into a single one before pushing to a remote/central repository for clarity. (The multiple local commits were for your own sake)
• You accidentally committed some sensitive data (i.e. hard-coded passwords) to a repository, followed by some other changes that also removed that sensitive data. You don’t want to strip the intermediate (password-containing) revision because of the subsequent work. You can combine the two to one revision that contains the subsequent work but no record of the sensitive data.

Folding will help in both situations.

Tutorial

This tutorial will cover folding using TortoiseHg, the popular GUI front-end for Mercurial. Before getting started, you’ll have to ensure that you don’t have any uncommitted changes, as you won’t be able to accomplish some of the steps with outstanding changes.

Open up the Repository Explorer. Below, you can see the example one, with our initial commit, which contained the sensitive data, followed by another that removed it. We’ll merge them into one.

Next, you’ll need to enable the Mercurial Queues extension, either through the TortoiseHg UI or by manually editing your mercurial.ini file or per-repo setting file. (.hgrc) Below, I’ve shown it in the UI: You need to check off the “mq” box under “Extensions”.

You’ll need to close the Repository Explorer and re-open it for the mq extension to take effect in the UI.

Next, select the oldest changeset and then right-click the newest one; in the context menu, select “Import from here to selected MQ”.

Then, open the Patch Queue by clicking its icon or selecting View > Patch Queue from the menu.

You should be able to see the changesets in your patch queue on the left side drawer. They’ll be labeled 0.diff, 1.diff, etc. You can also see which patch corresponds to which changeset because the imported changesets will have be labeled in the UI with qbase, qtip, 0.diff, 1.diff, etc. (They are listed in the patch queue in opposite order)

Now, right-click the top/oldest one in the patch queue, and select “Goto”. This will bring you back to the oldest changeset and remove the previous ones from your repository. But don’t worry, the changesets still exist in your (mercurial) queue.

Now, right click the next oldest one (which was removed from your repository), click “Fold” and then “Yes”. This will effectively fold or combine the two changesets into a single one with the equivalent changes/effects. Please note that this operation cannot be reversed, so make sure you really want to do it. (You did clone/backup your repository before starting, right?)

You can now adjust the commit comment/message and username, if you like, by clicking “Commit” or by selecting Tools > Commit from the menu. You may need to select View > Advanced to change/show the username. By default the commit message of the folded/unified changeset is an aggregate of the changesets that were combined to form it. You’ll probably want to adjust this down to something more meaningful.

After you are done, be sure to click “QRefresh” before closing the window.

After you’ve done the folding and modifying the commit message, you can right click the patch file (0.diff in this case) and select “Finish Applied” to put the folded/unified changeset back into your repository.

Your MQ patch queue should now be empty and the repository browser should show only one changeset, with your updated comments and no MQ tags/labels on the changeset. You can close the patch queue sidebar now, if you’d like.

There! Now all evidence of your nefarious activities has now been removed. Only the beginning and the end remain. Use wisely.

If you’re using jQuery, you’ll no doubt be aware of the click() method which can be used to trigger that event on an object. One would think that executing click() on an anchor element would cause the browser to navigate to the URL, but this isn’t the case. You cannot use jQuery’s click() method to fully trigger or simulate a user clicking on a link.

Instead, click(), when executed on links, only seems to trigger any event handlers attached to the DOM element rather than any default behaviour. I’m not sure if this is the case with other event methods or other DOM elements.

The solution

Instead, the solution is to directly manipulate the window.location object from JavaScript. One would think that since preventing the default action is quite simple (with jQuery’s event.preventDefault()), triggering the default action of a link click would also be. But this isn’t the case. Here’s a simple example on how to simulate a user clicking on a link.

In this contrived example, we have an ordered list of links that we’ve prevented the default action from executing on each. Instead, to activate a link we’ve provided an input box for the user to input the link number and then hit ‘Go’. When this happens, we grab the identified link and assign the href attribute value of the link to window.location, effectively recreating the default action of clicking the link.

HTML Source:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

  <title>jQuery Demos</title>
  <link rel="stylesheet" href="styles.css" media="all" />
  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
  <script type="text/javascript" src="scripts.js"></script>
</head>
<body>

<h1>jQuery Demos</h1>

<ol id="outboundLinks">
  <li><a href="http://www.google.com">Google</a></li>
  <li><a href="http://www.theglobeandmail.com/">The Globe and Mail</a></li>
  <li><a href="http://stackoverflow.com/">Stack Overflow</a></li>
</ol>

<p>
Link Number to activate:
<input id="linkNumber" type="text" size="3" />
<input id="activateLink" type="button" value="Go" />
</p>

</body>
</html>

JavaScript in scripts.js:

jQuery(function(e)
{
  jQuery("#outboundLinks").click(function(e)
  {
    e.preventDefault();
  });

  jQuery("#activateLink").click(function(e)
  {
    var links = jQuery("#outboundLinks li a");
    var value = parseInt(jQuery("#linkNumber").val());

    if (!isValidNumber(value, links))
    {
      window.alert("Invalid link number.");
      return;
    }
    else
    {
      // This won't work.  We cannot trigger the default
      // behaviour of clicking on a link this way.
      // links.eq(value - 1).click();

      // Instead, manipulate window.location directly.
      window.location = links.eq(value - 1).attr("href");
    }
  });
});

function isValidNumber(value, links)
{
    if (isNaN(value))
    {
      return false;
    }
    else if (value <= 0 || value > links.size())
    {
      return false;
    }
    else {
      return true;
    }
}

Note that window.location is not a regular property; it’s a special object that when assigned to, changes the URL in the address bar of the browser. There’s some debate over whether to directly use the location object or to use the window.location.href property.

This accomplishes the task of triggering the default action of clicking on a link, albeit in a roundabout fashion. Note that this example will only work for regular links that use href attributes as the source of the new URL. If you have links doing more complicated things via the use of event handlers (i.e. Ajax), then you’re better off using click() or directly invoking the JavaScript methods involved.

Motivation and Usage

There are numerous reasons for using the user’s location to improve the quality of a service. For example, the restaurant guide and review site, Restaurantica, automatically makes a guess as to your location and populates the “Search” field so that you are one click away from finding information tailored to your geographic area.

This determination is based on the user’s IP address. Usually, the lookup is done based on a static set of mappings from IP addresses to geographical locations, like cities. In fact, this is exactly what the IP address geolocation database (that we’ll use) does. It has the advantage of being easy to understand but unfortunately the accuracy can degrade over time, as IP addresses are usually not hardwired to specific locations. For example, most DSL users are subject to DHCP, so the same IP address may be re-used across different cities. (The IP address database from IPInfoDB is updated periodically to help reduce this inaccuracy)

Thus, you should not rely on the information provided to be 100% accurate; it should only be used as a suggestion. This is why Restaurantica only populates the search field with your estimated location, rather than giving you the results for that location right away; if it was wrong, the results for a different location would certainly be confusing to a user. This gives the user a chance to correct any inaccurate lookups.

Using the IP Address geolocation database

The first step is to download the database and import it into your local database; for this example I’ll use MySQL. Note that the site also offers an IP location Lookup API, which has the advantage of not requiring a local database but may be subject to usage limits; if you’ll be getting a lot of traffic you’ll be better off using the local database.

Import the contents into MySQL

I downloaded the Complete (City) database as one table in SQL format. Extracting the file from the archive, you’ll see that it’s well over 300 MB in size. If you’re fond of using phpMyAdmin, you unfortunately won’t be able to import such a large file using that tool, so we’ll have to rely on the command line to import the contents. Go to your mysql/bin folder and enter the following command, assuming you extracted the SQL file to the same location:

mysql -u root -p [name of database] < ipinfodb_one_table_full.sql

Running this command will take some time, as it won’t be fast having to import such a huge table. Take a break and come back in a few minutes. (You may want to create a new database to hold just this table, do that before running this command) After that’s done, you should be able to see the contents in phpMyAdmin, like below:

Using the database

Querying the database is straightforward, and the IP Info DB website has plenty of examples at the bottom of the download page. Basically, once you have the user’s IP, you can use a query like this to find the most likely city it originated from:

SELECT *
FROM `ip_group_city`
WHERE `ip_start` <= INET_ATON([ip address as a string])
ORDER BY ip_start DESC
LIMIT 1;

The INET_ATON function converts a string that is the dotted-quad octet form of an IP address (the form you’re most used to seeing) into a 32-bit unsigned integer. This integer is then used to locate the record that most likely corresponds to the geographical location. The database is structured such that row with the highest ip_start value not greater than the given IP address is deemed to be the most likely location.

An example:

SELECT * FROM `ip_group_city` WHERE `ip_start` <= INET_ATON('69.156.150.155') ORDER BY ip_start DESC limit 1;

(This returns the city of Toronto, Ontario, Canada) If you want to get a list of likely locations, just increase the LIMIT argument to something like 10, and this will return 10 locations that are likely close to where the IP address is located. Note that there may be duplicates in this list.

A simple example

Here’s a simple PHP script that takes the user’s IP address and displays their most likely location on a map using the Google Static Maps API.

<?php
$ipGeolocationDatabaseName = 'ip_geolocation';

$link = mysql_connect('localhost', 'root', '');
$ipAddress = mysql_real_escape_string($_SERVER['REMOTE_ADDR']);

echo $ipAddress;

mysql_select_db($ipGeolocationDatabaseName, $link);

$query = "SELECT * FROM `ip_group_city` " .
         "WHERE `ip_start` <= INET_ATON( '$ipAddress' ) " .
         "ORDER BY ip_start DESC " .
         "LIMIT 1";
$resultLocation = mysql_query($query);

$numRows = mysql_num_rows($resultLocation);

if (0 == $numRows)
{
  echo "No likely locations found.";
}

while ($row = mysql_fetch_array($resultLocation))
{
  echo "<pre>";
  print_r($row);
  echo "</pre>";

  $lat = urlencode($row['latitude']);
  $lng = urlencode($row['longitude']);
  if (!empty($lat) && !empty($lng))
  {
    // NOTE: Replace the `key` parameter with your own, obtained from:
    // http://code.google.com/apis/maps/signup.html
    // (The one in use is only good for URLs on `localhost`)
    $queryString = "center=$lat,$lng";
    $queryString .= "&zoom=10";
    $queryString .= "&size=300x300";
    $queryString .= "&markers=$lat,$lng,blue";
    $queryString .= "&key=ABQIAAAAicCf6MqoHlR-MsfivtVWPRT2yXp_ZAY8_ufC3CFXhHIE1NvwkxTNmqRdvnM9orG9QdyALHoUZfmFuQ";
    $queryString .= "&sensor=false";

    echo '<img src="http://maps.google.com/staticmap?' . htmlentities($queryString) . '" alt="location" />';
  }
}
?>

Here’s what it display for my IP address:

As you can see, it’s not always accurate, but it’s a good start to enhancing your website to offer localized services and features.

If you’re like me, you love shortcuts and other tools that improve productivity. One of the other things I’ve gained a liking for is the Bash shell, after spending time in a Unix environment. Since I couldn’t live without this, and the other tools that typically come with a Unix environment, I installed the great Cygwin, in order to create a Linux-like environment on my Windows PC. (Not ready to make the full jump to Linux yet, for gaming reasons)

However, one thing that always irked me was having to manually navigate to a certain folder after opening up a Bash shell in Cygwin. For Windows, there is a PowerToy called “Open Command Window Here”, that provides a context menu option for quickly opening a (Windows) command prompt with the location set to the selected folder. This is helpful, since you often have the folder open when you want to also have a command prompt at the same location. Now, all I needed was the equivalent function, but for the Cygwin Bash shell, instead of the Windows Command prompt.

Creating a “Bash Prompt Here” shortcut

I did some searching and found a myriad of solutions to my problem, most of which were somewhat complicated. Thankfully, I did find one link that suggested an easier solution.

Basically, here’s what you do. When you install Cygwin (of if you’ve already installed it, download it again and start setup again to run an update), make sure that you select the chere package under the “Shells” category.

After Cygwin is launched, open it up and type the command chere -i, like so:

You should now see the following option in your folder’s context menu, and more importantly, it works!

Hope you found this helpful!

function getPower(power)
{
  return function(x)
  {
    return Math.pow(x, power);
  }
}

var x3 = getPower(3);
window.alert(x3(3)); // Outputs 27.

In the rather stupid and contrived example above, we make a function getPower() that returns another function which raises the given value to the exponent supplied by calling getPower(). (This is a bad way to do things for numerous reasons, but is just shown for the sake of providing a simple example)

We then call getPower with a power of 3 and assign the returned function to the variable x3, and the output is as expected. Defining “inline” functions this way and manipulating them is closely associated with the concept of anonymous functions.

Functions: Copied and passed by reference

Since functions are objects, and objects are passed and copied by reference, the behaviour should be fairly straightforward to those familiar with the concept. Here’s a quick example of what I’m talking about. Since JavaScript functions can be treated just like plain old objects, this means we can attach arbitrary properties to them – let’s see how that relates to making a “copy” of a function:

function test() {window.alert("A Test");}
f = window.test;
window.test.aProperty = 'Hello!';
window.alert(f.aProperty); // Outputs "Hello!"

f.aProperty = 'Goodbye!';
window.alert(window.test.aProperty); // Outputs "Goodbye!"

The key here is that the expression f = window.test; doesn’t make a complete copy of the function; instead it just ensures that the variable f will point at the same function object as window.test. So expressions that modify the underlying function object and its data will reflect in both window.test and f. Just think of those two variables as being different ways of accessing the same underlying data.

But let’s consider another example: What happens if we make a copy of a function and then redefine the original?

function test() {window.alert("A Test");}

f = window.test;
f(); // "A Test"

// Redefine the original function.
test = function() {window.alert("A changed test");};

f(); // Still "A Test"!
window.test(); // "A changed test"

The results are a bit strange – it appears that when we redefine test, the changes are not reflected in the copy we created in variable f! Why is this?

Closer inspection yields the following answer: We were not actually redefining the function pointed to by test. Instead, we created a new Function object in memory and then “pointed” test at this new function. The old function, formerly referenced by test, is still referenced by the variable f so that is why it continues to invoke that code.

This is illustrated by the following diagrams. In the first, the original function has been defined and two variables refer to it.

In the second diagram, we have created a new function and altered the variable test to refer to it; however the variable f still refers to the original function. Thus, the important thing to note is that when using the assignment operator for functions, they are copied by reference.

The original function is still referenced by f

Where this matters

This point has relevance when talking about event handlers. Typically, when we bind functions to a specific events this involves copying a function reference over to some other variable or property. Whether we directly do this using traditional event registration by using an expression like element.onclick = someFunction or whether it’s done using jQuery’s Event Helpers, the effect is the same.

This means that after assigning the event handler, we cannot simply modify the original function to make changes to how the event handler works. This is because when we assign a new function the old one will still be referenced by the event handler. The proper way to do this at runtime would be simply to register the new function to the event and deregister the old one.

Another way to think of it is that you can often register anonymous functions to events; since they are anonymous you won’t have a reference to them after you assign them to the event handler so there is no way to modify them after the fact. This same logic applies equally when assigning non-anonymous functions to events.

A bit of background

However, what I want to discuss today relates to certificate chains. At the top of every certificate chain is a root CA, whose certificate is self-signed. This sort of certificate can be considered a “God certificate” because it essentially says, “Trust me, because I say so”. As you can imagine, that’s not much of an argument for trusting someone, so that is why your browser has a list of default root CAs that it automatically trusts.

Some default trusted CAs in Firefox.

These root CAs are owned and operated by companies that are in the business of issuing certificates to other people for use on their servers. They have been added to the default trusted list of most browsers so that an end user doesn’t need to manually add all of them; doing so would be a usability nightmare. Essentially, these root CAs provide a trust anchor point, as not only are they trusted, but any certificates they issue will also be automatically trusted by the browser. Attempting to visit a HTTPS/SSL website that does not have a trusted certificates results in a nasty warning from modern browsers.

Rarely is the root CA certificate directly used for a web server, but instead it is used to sign or issue other certificates that are then used on a web server to confirm its identity and provide for secure end-to-end communication.

As you can imagine, operating a CA is an immense responsibility, so that is why these default lists have been setup: Essentially these companies have to vet entities that purchase certificates from them, to make sure they actually own the domain that they are trying to buy a certificate for, otherwise phishing would become too easy! Even so, these companies sometimes still have lapses due to use of outdated technologies and poor security practices, but that is another complicated issue for another day.

Issuing a certificate – An example

The act of issuing a certificate essential entails a CA using its public-private key pair to sign the contents of the certificate that is being issued. This ties the identity information in the certificate to its key pair and provides confirmation that the CA has affirmed the authenticity of the certificate, I.E., that it has truly issued this certificate and that it has not been forged.

Going back to a certificate chains, it was previously mentioned that the root CA certificate is at the top of the chain. Any certificates it issues are directly below it, so if these certificates are directly used on a web server, then the chain is of length two. However, certificate chains can be longer. If a certificate chain is longer than two, then this indicates the presence of an intermediate CA.

An intermediate CA is a CA that does not have a self-signed certificate but still has the capability to issue certificates that are trusted. For an example of the root CA to intermediate CA relationship, we can look at the certificate chain returned from https://mail.google.com:

The Root CA certificate from VeriSign, an X.509 v1 certificate.

Above we see the root CA certificate, a self-signed certificate created/issued by VeriSign. I’ve highlighted the fact that it is an X.509 version 1 certificate, which also means it doesn’t have any certificate extensions. This may not mean much right now, but we’ll get back to it soon.

The Intermediate CA certificate from Thawte, an X.509 v3 certificate.

This next shot shows the intermediate CA certificate that was issued by the root CA. This certificate has been issued to Thawte, a company coincidentally founded by Mark Shuttleworth, the South African man behind Canonical/Ubuntu. Thawte was acquired by VeriSign during the dot-com craze for US $575 million.

The “Basic Constraints” extension of the intermediate CA.

We can clearly see that this certificate is an X.509 version 3 certificate, meaning it does support certificate extensions. One of its extensions is a Basic Constraints extension, which has been set to signify that this is indeed a Certificate Authority. It also specifies one other parameter, which is the maximum number of intermediate CAs allowed beneath this one in the certificate chain hierarchy. Since this value is set to 0, this means this intermediate CA cannot issue any more CA certificates, but instead can only issue client certificates. Any attempt will to use a client certificate from this CA as a CA or signing certificate will fail, when consumed by a conforming client.

The client certificate

The last screenshot shows the client certificate, which is the last certificate in the chain. This is the certificate that is used by the server at mail.google.com to secure HTTPS traffic, and as we can see, it is also an X.509 v3 certificate (has extensions) and one of those extensions is the “Basic Constraints” extension. This time it is set to indicate that this is not a CA certificate.

The Basic Constraints of the client certificate, indicating it is not a CA certificate.

Basic Contraints – Why it’s needed

The “Basic Constraints” extension is one way for a CA to control the usage of the certificates it issues. For instance, when the root CA certificate in the example above issued the intermediate CA certificate, it set the Basic Constraints extension to signify that:

• The issued certificate is for a Certificate Authority, i.e. an intermediate CA.
• This certificate may not be used to create further CA certificates

In turn, the intermediate CA certificate was used to create the client certificate for mail.google.com, and it attached a Basic Constraints extension to signify that this certificate was not a CA certificate. By doing this, it was indicating that this certificate should not be used to sign/create further certificates.

This is necessary because of the how trust relationship works in X.509 PKI. Someone who trusts the root CA implicitly trusts all the intermediate CAs, and then by extension, all the client certificates issued by those intermediate CAs! (Note how this creates a single point-of-failure at the root CA as well)

If the CA could not control what the certificates it issued were used for, then someone could purchase a VeriSign certificate and use it to sign/create other certificates which would also be trusted by default! Clearly, this is not desirably from a security or financial point of view, if you are VeriSign. By using extensions such as the Basic Constraints one, the signing CA can enact fine-grained control over how the certificate is used. If the client certificate was used to sign another certificate, that certificate would be rejected by a browser that conformed to the X.509 v3 specifications.

The Grey Area

However, we run into a “grey area” of sorts when faced with a certificate that does not have a Basic Constraints extension. In this case, it is not indicated whether this is a CA certificate or not. How do the browsers respond in this scenario? In this case, it seems to depend on whether the CA is a root CA or an intermediate one.

For root CA certificates, it seems that the Basic Constraints extension is not required in order for the CA certificate to be viewed as valid from the browser’s point of view. (I’ve observed this in Firefox and Internet Explorer) This most likely stems from the fact that there are root CAs that were created and put into operation well before X.509 v3 extensions were in wide use. The VeriSign root CA in our example is an X.509 v1 certificate with a starting validity date of 1996-01-28.

However, for intermediate CAs, it seems that the Basic Constraints extension is required if you want things to work, at least in Firefox and Internet Explorer. I encountered this situation when working with a Private Root CA of my own. I was trying to create an intermediate CA (without any Basic Constraints extension) from this root CA, and was running into problems when using this intermediate CA to create client certificates. Any of the client certificates from the intermediate CA were being essentially rejected by the browser when attempting to visit the website they were being used for.

Because this was a “grey area”, the results were mixed. In Firefox, the site would load correctly, however when attempting to view the certificate chain (by double-clicking the lock icon in the lower right), only the client certificate could be viewed, not the fully certificate chain. Internet Explorer would show the full certificate chain but simply failed to load the page. Neither browser gave any indication as to why things were failing.

However, once I created an Intermediate CA with a Basic Constraints extension set to explicitly signify that this was indeed a CA, everything worked as expected. I don’t believe this is well-documented, though this is understandable since most people will not be creating their own Private CAs unless it’s for a very specialized purpose.

How to do this using the Bouncy Castle APIs

I’ve talked about the Bouncy Castle Java APIs before, and they have been an invaluable resource for simplifying the creation of a Private CA and for issuing certificates.

When issuing a certificate it’s fairly easy to set the Basic Constraints extension to indicate you want the certificate to be a CA certificate. First, take a look at this guide to under the fundamentals of certificate creation with the Bouncy Castle APIs, then look at this code fragment:

private static final int NUM_ALLOWED_INTERMEDIATE_CAS = 0;
...

// Construct the certificate.
final X509V3CertificateGenerator certGen = new X509V3CertificateGenerator();

...

// Need this extension to signify that this certificate is a CA and
// can issue certificates. (Extension is marked as critical)
certGen.addExtension( X509Extensions.BasicConstraints, true, new BasicConstraints(
  NUM_ALLOWED_INTERMEDIATE_CAS ) );

...

final X509Certificate intermediateCaCert = certGen.generate( signingCaPrivateKey, "SunRsaSign" );

By doing this you ensure that the intermediate CA certificate has the proper Basic Constraints extension to work correctly with modern web browsers.

Conclusion

I hope you found this helpful. Certainly if you’re here, you’ve been puzzled over the same issues that I struggled through!

References

1. X.509 Public Key Certificate and Certification Request Generation
2. OID 2.5.29.19 – Basic Constraints
3. OID Repository – basicConstraints(19)

Delegation

Delegation is a fairly well-known design pattern. In short, it is a way for a method to produce its result simply by calling a method on another object, thus delegating responsibility to that object to provide the functionality needed by the method. For example, a Cashier object could store a delegate object called Calculator. Calling Cashier.addToTotal(value) would simply delegate to the contained object, calling Calculator.addToTotal(value).

How is delegation different than inheritance? With inheritance, the subclass inherits all of the functionality/behaviour of the parent class. You may not want or need this; in the preceding example, it would not make sense to have Cashier extend from Calculator simply because we wanted the addToTotal() behaviour/functionality. Delegation allows the behaviour advertised by a certain object/class to be provided by another.

Traditional Event Handling

In order to understand event delegation in JavaScript, we should first look briefly at how events are handled traditionally. When I talk of traditional event handling, I am referring to the model that most will know. In this model, functions are individually bound to events of certain elements. For example, to make all links turn bold upon clicking them (and prevent them from being followed), we could use some JavaScript like this:

window.onload = function()
{
  links = document.getElementsByTagName('a');
  for (var i = 0; i < links.length; ++i)
  {
    links[i].onclick = makeBold;
  }

}

function makeBold()
{
  this.style.fontWeight = 'bold';
  return false;
}

The key point with this example is that the function makeBold(), our event handler, is bound to each and every a element. From a resource point of view, this is may be a bad thing because the more event handlers that are attached, the more memory that is used, in general.

Of course, I promised I’d be using jQuery, and doing so cleans up the above code substantially, as well as making it cross-browser compatible: (Besides adding a ton of other abilities and making life easier)

jQuery(function()
{
  jQuery('a').click(makeBold);
});

function makeBold(e)
{
  e.preventDefault();
  jQuery(this).css('font-weight', 'bold');
}

While this code is cleaner, it still does basically the same thing as above, that is, the event handler function makeBold() is bound to each matched element, that is, each a element.

As a final note, don’t confuse my use of the term traditional with Peter-Paul Koch’s excellent guide to JavaScript event registration, where he uses the term traditional to refer to one method of event registration, distinct from inline registration and the later W3C and Microsoft “Advanced” event registration models.

Event handling using delegation

By contrast, event delegation uses a single (or comparatively few) event handlers to implement the behaviour required. This takes advantage of two key features of JavaScript events, namely event bubbling and the target event.

Event bubbling is a model for how events take place on the page. It grew out of a need to resolve the order in which events were triggered on ancestor and descendant elements. For example, assume that I have two event handlers, one attached to the “click” event of a div and another attached to the “click” event of an a element within that div. If I click the a element, which event fires first? Event bubbling is one way to solve that question: It states that the event on the inner element happens first, and then the event “bubbles” upwards to trigger events on ancestor or container elements. There is another opposing model that works in the opposite way, but bubbling seems to be better supported and is more relevant for this article.

Here’s a crude diagram of event bubbling, using a pseudo-CSS box model of sorts:

Event bubbling diagram

The event target is the DOM element that issued the event, or the originating element. This is why I believe it’s a confusing term, since it would make more sense to called it the event source. But I digress. The event object, passed to an event handler as an argument (or available via window.event, though jQuery normalizes this) contains a property, event.target, that allows you to get the reference to the “target” element that the event started bubbling up from.

How it’s implemented

All of this is typically accomplished by registering a single event handler to a “container” element that holds all of the elements we wish to react to events for. When an event is triggered on one of the inner elements, it “bubbles up” to the container element, where it triggers the event handler function. From there, we can inspect the source of the event (confusingly called the event target) and then react accordingly.

This is where the delegation aspect comes into play. Since the container element may hold many inner elements, it is unlikely that we would want the same behaviour for each element when an event was triggered on it. For example, we might want certain a elements to trigger one action when clicked, while wanting another set of a elements to trigger another action. We’d typically differentiate these links by using separate class names or by context and then attaching event handlers as appropriate.

Using event delegation, process is similar, but instead of attaching multiple event handlers we have one on the overall parent element. When this event handler is triggered, we determine which element triggered the event and then based on this, delegate the remainder of the processing to another function. An example would be helpful now, as our previous examples with making some text bold weren’t too useful. Here’s the XHTML fragment for the container and elements.

<div class="container">
<ul class="top">
  <li>
    <a href="#" class="expandList">Item A - Click to toggle</a>
    <ul class="hide">
      <li>Sub-item 1</li>
      <li>Sub-item 2</li>
    </ul>
  </li>
  <li>
    <a href="#" class="expandList">Item B - Click to toggle</a>
    <ul class="hide">
      <li>Sub-item 1</li>
      <li>Sub-item 2</li>
    </ul>
  </li>
  <li><a href="#" class="remove">Item C - Click to remove</a></li>
  <li><a href="#" class="remove">Item D - Click to remove</a></li>
</div>

And here’s the JavaScript:

jQuery(function()
{
  jQuery('div.container').click(handleEvent);
});

function handleEvent(e)
{
  // Obtain the source element through event.target.
  var target = jQuery(e.target);

  // Now decide what to do with it.
  if (target.is('a.expandList'))
  {
    // We use Function.call() to set the context for the `this` keyword.
    return expandList.call(target, e);
  }
  else if (target.is('a.remove'))
  {
    return remove.call(target, e);
  }
  else
  {
    // Otherwise, allow the default action to take place.
    return true;
  }
}

function expandList(e)
{
  e.preventDefault();

  // The `this` keyword now references the jQuery object representing the
  // target, since that is what we set the context to.
  jQuery(this).parent('li').find('ul.hide').slideToggle('fast');
}

function remove(e)
{
  e.preventDefault();
  jQuery(this).parent('li').fadeOut('normal', function(){jQuery(this).remove()});
}

With this example, the steps are clearly outlined. First, we attach the overall event handler to the container element; events that take place on its inner or children element will bubble up to it. When an event is received, we inspect event.target to determine the origin and based on that, “hand off” to another function to carry out the proper behaviour.

With some standardization of the CSS class names you use and the associated event handler function names, you can clean up this code to reduce duplication and turn it into a design pattern of sorts. In fact, that’s exactly what Dan Webb has done.

More advantages of event delegation

Besides potentially using less resources by having less event handlers bound, event delegation brings one other significant advantage: The ability to have event handlers “auto bind” to new DOM elements. For example, let’s say we were to dynamically update the DOM and add more list items to our previous example; this sort of action happens frequently during Ajax operations where you want to present new content to the user.

In the “traditional” event handling model, the new elements would not automatically respond to events as you would like. This is because the events were individually bound to each element. This is a well known problem. However, in event delegation, since there’s only one event handler bound to the container or ancestor element, the newly-created elements will respond to the event properly! This is because an event on them “bubbles” up to the container element just as for the original elements.

Demo of Event Delegation

Perhaps a little demo is needed. With this demo, you can see both the implementation of event delegation as well as the effect of adding new elements.

Drawbacks of event delegation

I’ve already talked about some of the benefits (fewer bound event handlers, so less resources used and the ability to adapt with DOM changes), but it’s worthwhile to iterate over some of the drawbacks.

1. Firstly, not all elements “bubble up” in the way described. The blur, focus, change and submit are notable exceptions so you will not be able to use event delegation with these events in the manner described in this article.
2. Furthermore, the code developed to maintain event delegation can be more complicated to understand than with just using the traditional model. Indeed, there is an initial investment time everyone must make to get going. This should obviously be considered since code maintenance is always important.
3. Because there’s one event handler being called for all events on inner/descendant elements, there can be some performance implications. If you’re calling expensive functions within this event handler, the event processing could slow down significantly. Careful optimization may be required.

However, some of these drawbacks can be mitigated by using solutions developed by the jQuery community. Even though event delegation is somewhat new, there are already plugins available that take a lot of the grunt-work out of event delegation, abstracting away the details and making things easier for you. Even jQuery itself also supports event delegation through a built-in function as of v1.3. Here are some options for pre-built solutions:

• Dan Webb’s Delegate Plugin
  This is a fairly straightforward way to implement delegation and it’s easy to setup and understand.
• jQuery’s built in live() function
  This supports a subset of events but is good enough for most uses.
• The Live Query plugin
  This is your best bet if you need the most functionality, though I haven’t personally tried it out yet.

Conclusion

Delegation nicely solves the problem of having to rebind events after adding new elements to the DOM. For that reason alone, I’ve started to use in my work more often. At its heart, it’s a useful design pattern, but should be only with full understanding of the pros and cons. I hope you enjoyed reading this article!

References

1. Event Delegation Made Easy
2. Event delegation without a JavaScript library
3. JavaScript Event Delegation is Easier than You Think
4. Why do my events stop working after an AJAX request?

Revisions

• 2009-02-20: Added a crude diagram of event bubbling

I’ve written about Eclipse and how useful it can be, with its extensible plugin-based system. It’s so useful that I use it everyday for almost any language – Java, PHP, JavaScript to name a few. It’s even great for things like CSS and XHTML.

PHP is currently my favourite “hobby” language and has been for some time. While I like PHP, one of the things that hasn’t been straightforward with it is setting up a proper debug session, where you can step through code. This contrasts heavily with a language like Java, which has always had strong developer tools. This has resulted in a mass of third-party tools aimed at facilitating PHP debugging. A while ago, a reader emailed me asking about this very topic, so I decided to put together how-to detailing my experience with the topic and how I went about learning it.

Xdebug for PHP and XAMPP

The debugger I’ll be using will be Xdebug. Because PHP provide no built-in debugging tools, there are many third-party options for debugging. (See the “Debugging Tools” section of this article for more) However, Xdebug seems to be one of the more popular ones, and Eclipse PDT already has support for it.

This guide also assumes use of XAMPP, the great all-in-one solution for quickly setting up a web development environment and to get your code running on the server. XAMPP is great for hitting the ground running, though you’ll probably not want to use it in a production environment – though you likely won’t be debugging there either. Nevertheless, the instructions provided here should work even if you’ve setup Apache and PHP separately on your own.

Getting started

The first thing you’ll want to do is head over the Xdebug page and download the appropriate Zend extension of Xdebug corresponding to the version of PHP you’re running. Save the file into your PHP extension path/folder. Now you’ll have to edit your php.ini file to begin using the plugin. The plugin basically exposes or provides an interface for the client debugger (running in Eclipse or your IDE) to attach to the server and debug/trace through the code that’s running on it. If you’re from the Java world, you’ll know this as “remote debugging”, which is provided by most J2EE application servers.

You’ll also want to have downloaded Eclipse PDT have that installed as your IDE, if you haven’t already done so. Zend Studio for Eclipse also works, since it’s based on Eclipse PDT, and offers quite a few more features, out of the box.

Setting up Xdebug

You should have already saved the Xdebug extension DLL file to your PHP extension folder. Record down the full path of it. Now, open up your php.ini file and go down to the [XDebug] section, or create it if it’s not there. Uncomment or add the following lines:

;; Only Zend OR (!) XDebug
zend_extension_ts="D:\XAMPP\php\ext\php_xdebug.dll"
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=9000
xdebug.remote_handler=dbgp

The zend_extension_ts should point to location of your Xdebug extension DLL that you downloaded earlier; modify as appropriate.

Then, you should disable the Xdebug entry in the list of dynamic extensions. This is confusing, but since we are already setting up Xdebug as a Zend extension, we don’t need another entry. Disable the Xdebug dynamic extension by ensuring the following line is commented out, like below:

;extension=php_xdebug.dll

There is one last very important step you need to do, particularly if you are running XAMPP. Current versions of Xdebug are incompatible with the Zend optimizer that is enabled by default in XAMPP, so you must disable that if you want Xdebug to work. If you don’t, you’ll notice that Apache will crash every time you try to load it with Xdebug enabled. To disable the Zend optimizer, find the [Zend] section in php.ini and comment out all of the entries under it, like so: (This is an example, there may be more to comment out)

[Zend]
;zend_extension_ts = "D:\XAMPP\php\zendOptimizer\lib\ZendExtensionManager.dll"
;zend_extension_manager.optimizer_ts = "D:\XAMPP\php\zendOptimizer\lib\Optimizer"
;zend_optimizer.enable_loader = 0
;zend_optimizer.optimization_level=15
;zend_optimizer.license_path =

You should be able to start Apache now without troubles.

Configuring Eclipse for PHP debugging

The next part will be configuring Eclipse as a debugging client. Since the code will be executing on the web server (Apache), you’ll need Eclipse to “hook in” using the Xdebug protocol. Thankfully, configuring Eclipse is fairly straightforward.

Open up Eclipse’s preferences and go to PHP -> Debug, and ensure that XDebug is selected as the PHP debugger. This sets the default for debugging sessions and lessens the configuration required for each debug session. You can also make sure that the default web server is localhost if that’s the case, which it’ll likely be for a lot of people doing development.

Note that if you are running Zend Studio, you’ll need to follow the steps in this article to enable Xdebug support. It seems that some versions of Zend Studio by default disabled support for the Xdebug plugin in lieu of their own Zend Debugger.

Now you can select a file from a project you’d like to debug. In my case, I’ve selected src/demo/index.php from my Challenge-Response PHP Login System project. Open the file, and then go to the Run Menu and select Debug Configurations… or Open Debug Dialog.

Double click the the “PHP Web Page” entry on the left side bar to create a new debug profile. Here, I’ve named it “CHAP-PHP”. You should see a dialog like the one above. Make sure the “Server Debugger” is again set to Xdebug and that the PHP Server is set to the localhost configuration you set up previously.

Then you have to select the file you want to debug. Click on “Browse”, and you’re confusingly taken to another view of your Eclipse projects; simply select the same file as before – you have to select a specific file, and not just a project or folder.

After that, you’ll need to adjust the URL mapping. You’ll probably need to uncheck “Auto Generate”, and then enter the URL that corresponds to the PHP file you’re debugging. Here, I’ve manually entered /projects/CHAP/trunk/src/demo/ as the URL fragment that triggers execution of the script.

If you want the debugger to stop right at the first line to allow you to immediately begin stepping through code, check “Break at First Line”. (It may be checked by default) Otherwise, uncheck it if you only want the debugger to stop at the breakpoints you’ve specified in Eclipse, which is the normal behaviour most developers will expect.

You should now be able to click “Debug”, and a debug session will launch, opening up the URL you’ve specified and allowing you to step through code. If you don’t like Eclipse using its own internal web browser (which appears just be a front for IE), you can configure which web browser you’d like it to launch URLs with by opening up Preferences and then going to General -> Web Browser and changing the setting to use an external web browser of your choice. Personally, Firefox is my preference.

Start your debugging engines!

You can now get acquainted with stepping through code, which in my opinion, is one of the best ways to learn! When you launch a debug session, Eclipse should prompt you to switch to a new “perspective”, which is just a different layout of Eclipse’s internal windows that many believe better suit debugging through code.

You’re provided with an informative view of the script your currently debugging, along with the highlighted line that execution has paused on. You can set debug breakpoints by double-clicking in the left margin of your source code view window; debug breakpoints show up as blue circles here. The buttons at the top (green “Play”, red “Stop” and others) provide control over execution of the code, allowing you to step through code line-by-line, step into functions/methods and return from them. I encourage you to experiment with all of the controls and get acquainted with the keyboard shortcuts.

Another panel also shows all the current variables available to the script as well as their values. This is useful since you now do not need to echo anything to output or change any of the code to see values.

When you’re done, you can just click the red “stop” button to disconnect from the server and end the debug session. If you’ve completely stepped through a script, you will not be automatically disconnected from the server. Instead, the debug client in PHP will patiently wait to debug the script again the next time it is executed. This is useful to know, since you can just go back to the URL in your web browser and reload the page to trigger the debug session to resume again.

Conclusion

I hope you found this useful, as when I was starting out trying to get a PHP debug session to work, it was somewhat frustrating. As always, I welcome your comments, suggestions and questions below via the comments form!

References

1. Why does xdebug crash apache on every XAMPP install I’ve tried?
2. Xdebug: Documentation
3. How to enable the Xdebug debugger in Zend Studio for Eclipse
4. Debugging PHP applications with Xdebug

Pop Quiz

Consider the following code fragment. We create a MapContainer object, and then get the contained map, which is guaranteed to have a certain value associated with the key “today”. We then alter the value associated with this key, using our local reference to returned map. We then query the MapContainer object and get the contained map again. What is the value associated with the key “today” in this map?

final MapContainer mapContainer = new MapContainer();
final Map<String, String> map = mapContainer.getKeyValuePairs();

final String today = map.get("today");
assert null != today;
System.out.println(today);  // Returns the current date-time.

// Change the value using our local reference.
map.put("today", "tomorrow");

final Map<String, String> mapAgain = mapContainer.getKeyValuePairs();
System.out.println(mapAgain.get("today")); // What is output?

Don’t waste too much time on this problem, as it’s a trick question. The answer actually depends on the implementation of MapContainer. Depending on how it’s implemented, the second output could be unchanged from the first or be changed to the new value of “tomorrow”.

It’s all in the getters

Let’s take a look at the code for MapContainer.

import java.util.Date;
import java.util.HashMap;
import java.util.Map;

public class MapContainer
{
  final private Map<String, String> keyValuePairs;

  public MapContainer()
  {
    this.keyValuePairs = new HashMap<String, String>();
    this.keyValuePairs.put("today", new Date().toString());
  }

  public Map<String, String> getKeyValuePairs()
  {
    return keyValuePairs;
  }
}

We have a simple constructor that initializes the keyValuePairs Map and adds one value for the current date-time. But the real ‘key’ (no pun intended) to solving the problem is looking at the getter for the field. As you can see, it simply returns a reference to the private field. Under this implementation, a caller is able to alter the contents of the private field/Map even though no public “set” methods are available. Why is this? For two reasons: In Java, objects are passed/returned by reference, and HashMap is a mutable object. Thus using this implementation, the second output from our original code fragment is “tomorrow”, since the caller has altered the contents of the Map through the returned reference.

Furthermore, the original reference returned from the getter is not independent either; if some other code were to call the get method on the MapContainer object and make changes to the Map, those changes would also be reflected in the original returned reference!

How can we “fix” this? We simply have to ensure that the getter for the field returns a reference to a copy of the private Map. This is easy since there is a constructor for HashMap that accepts an existing Map. Here’s the altered code:

import java.util.Date;
import java.util.HashMap;
import java.util.Map;

public class MapContainer
{
  final private Map<String, String> keyValuePairs;

  public MapContainer()
  {
    this.keyValuePairs = new HashMap<String, String>();
    this.keyValuePairs.put("today", new Date().toString());
  }

  public Map<String, String> getKeyValuePairs()
  {
    return new HashMap<String, String>(keyValuePairs);
  }
}

With these changes, the private Map cannot be altered by a caller and thus the second output will remain changed in our first code fragment example.

To change, or not to change?

It should be noted that sometimes you may want to allow callers to alter the backing data structure that you return from a get method. For example, some of the data structures from the Java Collection Framework have getters that return references that can be used to alter the state of the original object. A good example is the entrySet() method of the HashMap object.

But in my opinion, these examples are the exception rather than the rule. In general, you do not want to allow callers to be able to alter the state of private fields directly since this violates information-hiding principles. If there is some change a caller needs to make to your object, it’s best accomplished through a set method since this allows you to control the changes and prevents unwanted/unexpected situations. If you do decide to allow callers to directly alter the state of private fields, it’s best to explicitly document this in the JavaDoc.

Mutability and safety

Note that in this example the field used was a HashMap object, which was mutable. If the field consisted of an immutable object, like a String, you would not have to worry about making a copy before returning it. This is because if the object is immutable, you do not have to worry about a caller changing its state because this is impossible to do! This is why immutable objects are much easier to deal with in multithreaded/concurrent environments.

Note that mutability has nothing to do with the final keyword in Java, contrary to this definition. Simply marking a field as “final” will not magically change a mutable object into an immutable one. As we saw earlier, whether an object is mutable or not depends entirely on its implementation, the details of which should be expressed in the JavaDoc for that class. The final keyword only ensures that you cannot reassign that field/variable to completely new reference or object; it does not ensure that you can’t change the state of the object already referenced.