Friday, February 25, 2011

Do not return in a finally block: return will swallow your exceptions

This is a blog post that should not be. Unfortunately, this is a recurring mistake I'm seeing out there and hope this can help people prevent it.

Yesterday I've been busy troubleshooting a problem we were experiencing in a cluster of application servers. We narrowed down the problem to a module implementing the JAAS login protocol and, according to the failing module documentation, we should have received a LoginException generating from an UnsupportedOperationException launched down the call stack. Instead, the module was silently failing and returning a reference to a partially constructed JAAS Subject.

We checked out the module source code and it took us few minutes to detect the problem. The module was correctly implementing its documented protocol and was generating the UnsupportedOperationException as expected. The author, unfortunately, forgot one of the rules of the Java Language and was returning from a finally block, effectively discarding the exception that was launched just a couple of lines before.

That's amazing how many times I see people returning from a finally block without understanding what the code is intended to do.

Still not convinced?

Run this:

@Test
public void hello() {
    try {
        throw new UnsupportedOperationException();
    } finally {
        return;
    }
}

No exception is thrown. Surprised? You should not. There are plenty of variations of this theme out there. Nevertheless, if you're still surprised that the hello() method completes without throwing an UnsupportedOperationException, please read on.


try/catch/finally blocks

According to the Java Language Specification, this is a simplified vision of what happens during the execution of a finally block (you can read the normative documentation here):
  • If the finally block completes normally, then the try statement completes abruptly for reason R.
  • If the finally block complete abruptly for reason S, then the try statement completes abruptly for reason S.
As you may notice in the JLS, then, the "reason" a try statement completes with will always be affected by an abrupt completion of a finally block. Said in other words, the finally block will "decide" what happens later.

You probably though many times about what happens if an exception is thrown in a finally block, don't you? Perhaps you even tested that case: the exception that will be propagated up the stack will be the exception launched in the finally block. That's not surprising, after all, and that's why you should carefully check that the code in finally blocks don't fail without control.

So far, so good. But what happens, then, when a return statement is executed inside a finally block?


The return statement

What Java programmers often misunderstand is the very nature of a return statement. The Java Language Specification is clear about that:

The return statement always completes abruptly.

That's why exceptions launched in try or catch blocks (the "reason" of their abrupt completion) are simply ignored and not relaunched when a finally block completes abruptly with a return statement, being that the "resulting" reason of the abrupt completion of the try statement, as seen in the previous section.


Lesson learned

I personally don't see any good reason, unless you want any exception to be swallowed, to return in a finally block: it defies the very reason for try/catch blocks to exist.

Do think twice (or more...) before using this construct: chances are you're doing a favor to others and yourself if you avoid it.

Sunday, February 20, 2011

Your Glassfish instance doesn't start. Have you checked the OSGi cache?

I've seen this many times: you just upgraded your NetBeans and the bundled Glassfish and it suddenly stops responding. Or maybe you upgraded a Glassfish instance and your domain fails to start leaving you watching and endless stream of dots and no further activity:

$ asadmin start-domain your-domain
Waiting for DAS to start......................
$ vmstat 1

 kthr      memory            page            disk          faults      cpu
 r b w   swap  free  re  mf pi po fr de sr s0 s1 -- --   in   sy   cs us sy id
 0 0 0 945484 1100116 222 58 947 7 7  0  0  0 12  0  0 1423 1516 1185  3  1 96
 0 0 0 838032 1383588 7  23  0  0  0  0  0  0  4  0  0  601  757 1085  0  1 99
 0 0 0 838032 1383588 4   4  0  0  0  0  0  0  1  0  0  598  782 1071  0  0 100
 0 0 0 838032 1383588 4   4  0  0  0  0  0  0  0  0  0  565 1079 1296  1  0 99

If this is happening to you, chances are that the OSGi cache of your domain is poisoned and prevents your server from working properly. In this case, try to clean it up with ($GR is Glassfish installation root):

$ rm -r $GR/glassfish/domains/your-domain/osgi-cache

and start the server again.



Upgrading Oracle Glassfish Server to v. 3.0.1

Since version 3, Oracle Glassfish Server, formerly known as Sun Glassfish Enterprise Server, bundles an IPS-based "update tool" that makes life easier to system administrators while upgrading their Glassfish instances.

The update tool, a standalone GUI application, has been integrated into the Glassfish Admin Console since version 3.0.1, and can now be easily used to check installed components or available package updates.



The update tool can be found at $GLASSFISH_ROOT/updatetool/bin/updatetool or, starting with version 3.0.1, at $GLASSFISH_ROOT/glassfishv3/bin/updatetool.

Sometimes, though, administrators prefer using a safer upgrade path than patching a running instance, in case they need to quickly rollback to the previous instance in case something goes wrong.

As described in the official Glassfish documentation, administrators can now use the asupgrade tool to upgrade an existing Glassfish domain to a new installation path so that, if the upgraded instance does not work properly, they can fall-back to the old one.

Upgrading Glassfish using the asupgrade tool is straightforward:

  • Install the Glassfish instance you're going to upgrade to. If you're using the zip distribution, just unzip it.
  • Stop the domain to be upgraded.
  • Launch the asupgrade tool to upgrade a Glassfish domain:
asupgrade [-c] \
  --source /old/domain/path
  --target /new/domain/root/path

The optional -c option instructs asupgrade to use the upgrade command line utility instead of the default GUI upgrade utility. This is handy when you need to upgrade instances on remote machine and you cannot, or wish not, use a GUI interface.

Please note that the --source argument points to a domain while the --target argument points to a domain root. You should, then, use something like this:

asupgrade -c \
  --source /opt/ogs-3/glassfish/domains/domain1
  --target /opt/ogs-3.0.1/glassfish/domains

Depending on your domain name, the tool may ask you whether you wish to rename an existing domain on the new server instance. That's typically the case when you're upgrading a domain called domain1 since the default Glassfish installation bundles a domain with such a name.

The tool will start the upgrade process that will be logged in the upgrade.log file for later inspection. If the upgrade process finishes correctly, you can now start the upgraded instance and check that all of your applications work as expected.

So far, I haven't experienced any major problem with the asupgrade tool and it's a very easy upgrade process that takes care of everything. Resources such as data sources, connection pools, JavaMail sessions, were all replicated correctly on the destination server. The tool even took care of copying the database drivers from one instance to another.

The only glitch I experienced is being unable to start the server without cleaning up the OSGi cache first but that's easily solved.