Java Checked vs Unchecked Exceptions


Today I have decided to write an article not so related to game development (yes, JevaEngine is coming along very nicely in-case you are wondering.) Instead I will be focusing on the difference between checked and unchecked exceptions, what the general consensus is on them and my opinion on them.

First, lets define quickly the differences between the two types of exceptions and what their intentions are, then I will go through my experiences with either one and where I rest my opinions now.

Checked Exceptions vs Unchecked Exceptions

An unchecked exception is your conventional exception. It can be thrown from anywhere, and it can be declared in a try-catch clause anywhere. Some typical examples of this are (in the JDK) IndexOutOfBoundsException, IllegalArgumentException etc... These exceptions are designed to be thrown when the programmer is using a particular interface incorrectly [Not all API designers take this approach.]

For example, the following code will throw an unchecked NullPointerException, opposed to a checked FileNotFoundException.

String fileName = null;
try(FileInputStream fis = new FileInputStream(fileName))
} catch (IOException e) { }

Checked Exceptions are used to describe errors that may occur, and their ability to occur is entirely out of the hands of the programmer using the interface throwing them as well as the interface implementation itself. That is to say that even if the interface is used 100% properly, and its implementation is 100% free of bugs, it still may encounter an error performing its task. So for example, you could reconsider the FileNotFoundException shown above. Whenever you open a file, you must deal with the possibility that it does not exist. Whenever you open or read from a file, you must deal with the possibility that an IOException occurred when attempting to gain access to the files data.

That means that you should never be catching an unchecked exception in most circumstances [with some exceptions stated below.]

Where it gets interesting

Sometimes you will encounter situations where a checked-exception being thrown by an interface should be, in your very particular circumstance, interpreted as a unchecked exception. These are *rare* - and you should almost never do what I am about to show you (if you don't think checked exceptions are evil - otherwise you probably already do it all over the place...)

Consider the following code sample:

try {
	URI files = new URI("file:///a/b/c.txt");
} catch (URISyntaxException ex) {
	//This will never happen

In this case, we are providing the constructor of URI a valid syntactically correct URI, but we are still forced to catch the checked exception. In our particular circumstance, since the URI String is being defined by the programmer [and is not being provided by a source out of our control such as a text document or a user text field] it is actually an unchecked exception. As per our definitions above.

In that code sample, what we are doing is converting a checked exception to nothing. This is _very_ _very_ bad. This means that if someone comes along and changes that syntactically correct URI String to something syntactically incorrect, no one will ever know. They will get a NullPointerException when trying to reference the URI. Instead it is better to rethrow the exception as an Unchecked Exception.

try {
	URI files = new URI("file:///a/b/c.txt");
} catch (URISyntaxException ex) {
	throw new RuntimeException(ex);

Again, converting from an checked exception to an unchecked exception should be done with very careful consideration.

Now that I've made my point, URI actually provides a static convenience method for doing something very similar to this:

URI files = URI.create("file:///a/b/c.txt");

Going the other way

Sometimes you'll find some interfaces will assume the opposite to what is being assumed by URI's constructor. Namely, they will assume the arguments are being provided by the programmer and not the user. A good example of this is the valueOf static method of the class Integer. This method throws an unchecked NumberFormatException if the provided argument is not a valid integer.

If the argument being provided to valueOf is provided by an external source [text document, database, user interface] and cannot be guaranteed to be a valid integer then it should be caught and wrapped in a (ie FormValidationException) checked exception and be rethrown.

Leaky Abstraction

A popular argument _against_ checked exceptions is that they force/encourage a leaky abstraction. The reason people argue this is because they do not understand when you should stop throwing up a checked exception, and instead handle it or wrap it. They may also fail to understand one of the core abilities of an Exception [wrapping.] Lets start by describing the most common tools used for abstraction.

What is the core function of an interface? [not a Java interface - but an *interface.* Ie as per our definition, a concrete class also has an interface component, such as public members.]

Interfaces provide a means to communicate with an implementation (the specific mechanics of a solution.) They are _not meant to expose_ the mechanics or any details regarding them. If they do, then they leak details through the abstraction they mean to provide (Ie, the interface provides a _leaky abstraction._)

It is important to appreciate that checked exceptions are apart of your interface. In an interface they are meant to communicate the possible failures without exposing details regarding the mechanics of a solution. If you declare them incorrectly, then they too can be the cause of a leaky abstraction. Since error handling can be difficult, and abstracting mechanics can be difficult, you'll find a lot of programmers blame exceptions for their leaky abstraction. The trick to integrating checked exceptions into your application without leaking the abstraction is understanding when to handle exceptions caused by your implementation/mechanics, and when to wrap them & expose them to the user of your interface.

Exposing errors caused by your implementation through your interface

If you are have an interface that provides a particular abstract function, and an implementation of this interface encounters a error while performing that function, it should throw a checked exception that makes sense to the interface being used. For example:

You are contracted to work on an existing application that is a word processor. It currently has the feature to read documents from the local storage devices. It was well designed, so all of it's resources are accessed through a FileSystem interface. The FileSystem interface is designed like so:

public interface FileSystem
    InputStream open(URI name) throws FileInaccessibleException;
    public static final class FileInaccessibleException extends Exception
        public FileInaccessibleException(URI fileName, Exception cause)
            super("Unable to locate the file: " + fileName, cause);

The current implementation of FileSystem looks something like this:

public class LocalFileSystem implements FileSystem
    public InputStream open(URI name) throws FileInaccessibleException
            return new FileInputStream(new File(name));
        } catch (FileNotFoundException | IllegalArgumentException e)
            throw new FileInaccessibleException(name, e);

What we need to do is create our own implementation of this FileSystem interface that connects through a network and performs the same tasks. Lets assume that our implementation encounters an error opening a file due to it not being connected to a specific server from which to fetch these documents from. How would we communicate that error through the interface?

We could wrap a FtpFileSystemNotConnectedException through our interface by wrapping it with the FileInaccessibleException.

What if, in the middle of reading from a FtpFileInputStream, we are disconnected from the server? We can throw a FtpFileSystemNotConnectedException wrapping in an IOException.

Now presenting these errors to the user is another story. It is best to display the exception message, and then log the stack trace (for the developer to use if it was a logic error that lead to the throwing of the exception. [Your stack trace and your exception names is usually enough to resolve a logic error if the programmer needs to.]

Now you've only changed one interface, and you've added an incredibly complex feature. The application is inherently designed to deal with all the complex errors that can occur over a network communication etc.

When to stop propagating errors, and handle them.

Eventually you need to handle the checked exception. They are checked because they need to be handled. The way you can handle them can range from simply notifying the user that the service is not available due to X reason or provide a limited access to the component that depends on that service.

It is very important that when you are providing a limited service, or resulting to default (null) behavior, you log it & and the stack trace. Otherwise errors can be difficult to discover and locate. Here is a simple example of when you can provide null/default behavior.

The EntityFactory in JevaEngine throws a EntityConstructionException when it cannot sufficiently construct an entity for the game world. However, the factory tries its very best to construct the entity. If the only error occurs when attempting to evaluate the entity's associated behavior script, it is provided a default behavior.

Likewise, the WorldFactory will ignore entitys that cannot be constructed - rather than failing to construct the entire world. Of course it is important to log the exception that caused the entity to fail in construction, and the fact that the entity was excluded from the world. Otherwise it can become difficult to identify the reason behind its exclusion.

You could simplify the solution by simply throwing a WorldConstructionException as well, depending on how critical it the failed component is to the application.

My Experience with Checked/Unchecked Exceptions

Let me start by saying that I used to very much dislike checked exceptions. I would constantly let them propagate out and crash the entire system with a stack-trace to examine. That may work for very simple applications or very deterministic solutions. However, I found that as my game engine became more complex this behavior was simply unacceptable. For a lot of reasons, here are a a few I discovered over the 3+ years I've been expanding on JevaEngine:

- Large & Complex frameworks have very deep execution paths. If someone is using your framework and a syntax error crashes the entire application due to a low-level dependency failing you're going to be really chocked. Yes, programmers should read documentation and understand their frameworks & the exceptions they can throw - but the ability to distinguish between a programmer error and a dependency failure is an incredibly beneficial feature people should be taking advantage of.

- An interface's implementation should evolve, but using checked exceptions lets you be 100% sure the user of that interface is not receiving any unexpected exceptions. Ie, that there is a consistent contract between the user of an implementation and the implementation in terms of error handling.

- If you're building a framework, you should opt for checked exceptions. Why? Because using applications that don't cohere with your exception handling model (use of checked or not) is a huge pain in the ass - but if you don't use checked exceptions and a user of your framework does it has the potential of introducing stability risks.

Scenario Drivers

I've come up to a reasonable solution to make the development of scenarios in JevaEngine significantly simpler and comfortable. First, we must define what a scenario is.

A scenario, in abstract terms, describes a series of events (as well as a sequence in which they must take place) and how the world reacts to the occurrence of these events. Scenarios can be incredibly simple or very complex. Typically, they are constructed by associating concrete behavior to particular entities. Ie, the logic of the scenario is not centralized but rather scattered across various entities.

Consider the following example scenario where in the player must kill a goblin, acquire a key from their corpse and then open a door. In this example, the behavior might be distributed as such:

You might construct a special item called "Key to Door Y." The key in-itself has no behavior and is merely a means for the critical components in the scenario (the goblin and the door) to communicate. The key is uninteresting to the player once he passes Door Y and outside of this function it serves no purpose.

The goblin may be a typical NPC. It could be one you spawn like all others, but it would require at least some specific configuration for its act in this scenario. It might be a configuration you call 'questGoblinDoorY' with the behavior adding the special key to its inventory.

The door would need to have a tailored behavior to open only under the circumstance that the player has the required key.

As you can imagine, the development of such a simple scenario ends up become very tedious. Now imagine multiple scenarios occurring in the same scene. That makes the development process significantly worse and stressful.

As a means to centralize the configuration of scenarios, I have decided to develop and use ScenarioDriver entities. They drive a scenario described in freemind. Here is a sample scenario I have developed thus far in freemind.

Using XSLT, I intend to transform this into a format that can be parsed by the Scenario Driver entity.

The victim's hotel room...

May be worth investigating the victim's hotel room.

Design your dialogue in JevaEngine using freemind.

I have written a custom XSLT (along with several changes to the dialogue system in the RPG base) that allows you to design your character dialogue in an mind-mapping utility called FreeMind. Here is quick demonstration (I'm short on time, and a picture is worth a thousand words...)

Note that the dialogue you are about to see demonstrated is meant to project a real murder case, and is thus graphic in nature.

A screenshot of Demo3

Demo 3 is getting really close to being completed. There are a few issues/bugs to resolve.

Demo3 uses PARPG assets to construct an "investigation" quest. Unlike Demos 0-2 which are more action rpg orientated using the FLARE RPG assets.

Imported PARPG assets for demo, improved rendering system a bit

As you may know, ISceneBuffer objects are responsible for handling rendering in JevaEngine. Today I've found some time to add a new ISceneBuffer object to JevaEngine's core. There are now two ISceneBuffers built into JevaEngine (it is very easy to use your own.)

- PaintersIsometricSceneBuffer which uses the painter's algorithm for rendering isometric scenes. This method is very quick but frequently fails if your scenes are not composed of strictly fixed sized blocks. It sorts based on the location of the entity - but ignores the containing bounds of that entity. Thus this makes it impossible to depth sort walls or gates that span across multiple tiles properly without breaking them into individually size tiles.

- TopologicalIsometricSceneBuffer is much more proper in terms of depth sorting scene components. It works with variable sized components and allows entities to be sorted properly on the Z axis. However, this sorting algorithm is much more expensive and has a complexity of O(n^2) That said, I have managed to get very large scene to be sorted in a manner of 1-2ms - which is perfectly acceptable.

Here is a test for the TopologicalIsometricSceneBuffer. You'll see the scene components and their respective AABBs.

There are three components visible in this image, the gas tank, the wind mill and the ground (which is a single component.)

In previous screen-shots, the ground was composed of many different components - each per tile. With this new depth sorting algorithm, the ground can be a single sprite (generated via tiled or rendered out of blender etc...) You can imagine that generating the meta-data on a per-tile basis would be a lot of work (especially if you have a lot of tiles) so it is much more optimal to import them into tiled, construct a tile-able surface texture 20x20 tiles in dimensions use that instead.

Demo 2 - Quest Demo

Demo 2 demonstrates how you could use JevaEngine to implement various quest using a combination of quest-controlled-NPCs, and area triggers to initiate character dialogue. It also demonstrates how to use the dialogue system implemented by the RPG Base.

Below is a layout of our world in the world editor:

In the bottom left corner, you'll see a named entity placement "player." If we look at its import declaration (which can be edited via the GUI in the world editor - but I will list the JSON for convenience.)

    "location" : {
      "z" : 1.0099999904632568,
      "y" : 44.0,
      "x" : 19.0
    "direction" : 8,
    "name" : "player",
    "config" : "artifact/entity/zombie/zombie.jec",
    "auxConfig" : {
      "behavior" : "artifact/behavior/character/puppet.js"
    "type" : "character"

A few sample scripts!

Hey! I've basically got JevaEngine's demos to a near complete state. I thought I would share some of the scripts I have driving the behavior used in the demo.

The first script is called the "puppet" behavior. When used by an RpgCharacter it remains idle until given abstract commands. For example "attack x" or "move to y." Essentially making it a puppet. It is useful in quest scripts where you are controlling special quest characters etc (i.e, to attack the player when they enter a trigger, or speak to the player when they come near etc...) Additionally, it is also used as the player character behavior (since the player's character is a puppet to the player.)

Note that these scripts I am posting are a little hacky/messy. They are more of a means to an end design rather than thoroughly thought through implementations. They are not critical in any sense to the engine or rbgbase. They serve specifically as samples & behaviors for driving the demo. They may contain bugs etc.

var g_attackTarget = null;

var g_attackRange = 0;
var g_attackSound = null;
var g_attackDamage = 0;
var g_attackPeriod = 0;

var g_dieSound = null;

var g_controlQueue = new Queue();

me.onEnter.add(function() {

	//Upon entering a world, initialize with configuration parameters.
	var config = me.getConfiguration();

	if (config.childExists("attackDamage"))
		g_attackDamage = config.getChild("attackDamage").getValueInt();

	if (config.childExists("attackPeriod"))
		g_attackPeriod = config.getChild("attackPeriod").getValueInt();

	if (config.childExists("attackRange"))
		g_attackRange = config.getChild("attackRange").getValueDouble();

	if (config.childExists("attackSound"))
		g_attackSound = config.getChild("attackSound").getValueString();

	if (config.childExists("dieSound"))
		g_dieSound = config.getChild("dieSound").getValueString();


function constructTasks() {
	// Double check to assure we are constructing over a clean slate.

	//If we're dead, there are no tasks that we can do...
	if (me.getHealth() <= 0)

	var controller = g_controlQueue.poll();

	if (controller != null) {
	} else if (g_attackTarget === null || g_attackTarget.getHealth() <= 0) {
		g_attackTarget = null;
	} else {
		var deltaFromTarget = me.getLocation().difference(g_attackTarget.getLocation());
		var distance = deltaFromTarget.getLength();
		if (distance <= g_attackRange) {
		} else
			var targetLocation = g_attackTarget.getLocation();
			me.moveTo(targetLocation.x, targetLocation.y, g_attackRange * 0.95);
			me.invokeTimeout(2000, constructTasks); //reconstruct tasks as it is likely that our target will move.


me.doAttack.assign(function(attackee) {
	var distance = me.getLocation().difference(attackee.getLocation()).getLength();
	if (distance >= g_attackRange)
		return false;

	attackee.invokeInterface("damage", g_attackDamage);

	if (g_attackSound !== null)

	return true;

me.onLookFound.add(function(target) {
	if (me.isConflictingAllegiance(target) && g_attackTarget === null) {
		g_attackTarget = target;

me.onHealthChanged.add(function(delta) {
	if (me.getHealth() === 0) {
		if (g_dieSound !== null)

me.mapInterface("target", function(target) {
	g_attackTarget = target;

me.mapInterface("damage", function(delta) {
	me.setHealth(me.getHealth() - delta);

me.mapInterface("queryControl", function(handler) {
	g_controlQueue.add(new CharacterController(handler));

function CharacterController(handler) {
	this.handler = handler;

CharacterController.prototype.doTasks = function() {

CharacterController.prototype.moveTo = function(x, y) {
	me.moveTo(x, y);

CharacterController.prototype.speakTo = function(subject, dialogue) {
	me.speakTo(subject, dialogue);

CharacterController.prototype.setFlag = function(flag, value) {
	me.setFlag(flag, value);

CharacterController.prototype.idle = function(length) {

Changes to JevaEngine's Scripting System

As you know, there have been some very large refactors in JevaEngine. These have allowed much more flexibility in JevaEngine - specifically the ability to use various different script engines. In this abstracting, I've also had to reorganizing the interface to these scripts. Here are some notable changes:

In the previous implementation of JevaEngine's scripting engine, you would have defined your methods in the global scope (of the script.) These methods would then be identified as handlers/delegates by their container (ie an entity) using their name/signature. There were a couple notable issues with this methods:

1. It littered the script's namespace. One could define a method without the intention of it being a handler, but by virtue of having the proper name/signature, the script's container would recognizes it as an event handler or delegate. For example, consider the onAttacked handler. Previously, it would be defined like so in the behavior script:

function attacked(attacker)
... Some event handling code

It is difficult to determine the purpose of this method. It may be used internally by the script, or it may be an event handler. One may define a method such as this with the intention of having it be used internally, but it would be acknowledged by the script's container (an entity for example) as a handler/delegate.

2. It made developing/debugging more difficult and the errors in scripts more difficult to identify. Failing to register a handler or delegate would be met with no immediate execution errors. One would simply observe absent behavior. For example, had the 'attacked' method above been named 'atttacked' instead (note the typo) the code would execute without any errors or warnings, yet one would observe the attack response behavior to be absent had they the luxury of testing the script in such an environment so readily.

The new method for registering handlers and delegates is much more efficient and resolves both of these issues. One would now do the following to register an 'attacked' handler.

me.onAttacked.add(function(attacker) {
..Handle attacked event

Also note that this allows for various different functions to be assigned to (or 'listen' to) events such as being attacked. Likewise, to register a handler:

me.doAttack.assign(function(attackee) {
..Do attack

You may have also noticed that in recent commits the feature to access a scripts defined methods/variables via the getScript method exposed on an entity's bridge was added. This has since been removed. The Entity Bridge being publicly accessible violated the privacy/control held by the respective behavior script and allows one to create unpredictable changes to the behavior's state/environment without warning. In the upcoming commits, the getScript method has been removed.

However, one will still likely need to obtain some interface/control over an entity externally (such as controlling a player for a quest script.) All entities now have a method called mapInterface (accessible only to the behavior script) and invokeInterface. This allows interface methods to be invoked and mapped, allowing one to control the entity via an interface presented by the entity's behavior script.


Subscribe to JevaEngine RSS