Home  Exceptions  try/catch  finally  Throwing  Exception hierarchy  Unchecked exceptions  Exception recasting  Uncaught exceptions

Throwing an exception in Java

In our discussion of exceptions in Java, we've so far treated exceptions as being mysteriously thrown at some point, and focussed on the process of catching or handling them. In some cases, exceptions are indeed "magically" thrown by the system. Various exceptions are thrown at the bytecode or system level, such as when an integer division by zero is attempted, when an attempt is made to access an invalid array index, or when Java's object allocator runs out of heap memory. However, a program can also deliberately throw an exception. Many exceptions that occur are deliberately thrown by Java library code or by user code when they detect a particular error condition.

To throw an exception, the throw keyword is used, followed by the exception object to be thrown. The most common case is to create the exception object on the fly, so that the code to throw an exception looks as follows:

throw new IOException("Some required files are missing");

We can create an instance of any public exception class from the libraries, or we can create our own exception subclass.

Some commonly thrown exceptions

There are certain exceptions that it is common and good practice to throw at the beginning of a method. They are basically unchecked exceptions: that is, our method doesn't need to state that it throws these exceptions. They can just be thrown at any time in any method:

IllegalArgumentException

If your method only accepts arguments within a particular range, e.g. only positive numbers, then you should check for invalid parameters and throw an IllegalArgumentException. For example:

public int calculateFactorial(int n) {
  if (n < 0)
    throw new IllegalArgumentException("n must be positive");
  if (n >= 60)
    throw new IllegalArgumentException("n must be < 60");
  ...
}

NullPointerException

If you know that a parameter to your method cannot be null, then it is best to explicitly check for null and throw a NullPointerException. That way, the problem is detected "there and then", rather than at some mysterious point further down when part of your code tries to access the object in question.

IllegalStateException

This one is a little less common, but is useful a method relies on a previous method having been called. For example, if your object requires its initialise() method to be called before other methods, then you can set a flag inside initialise(), and throw an IllegalStateException if initialise() hasn't been called:

private boolean initted;

public void initialise() {
  // ...
  initted = true;
}
public void doSomething() {
  if (!initted)
    throw new IllegalStateException("Object not initialised");
}

UnsupportedOperationException

This exception is designed for cases where you override an abstract class or implement an interface, but don't want or can't to implement certain methods. It is used by various classes of the Java Collections Framework. Ideally, your interface or method should also provide a means for the caller to determine in advance whether it expects the given operation to be supported.

RuntimeException and InternalError

These essentially mean "that should never happen and I don't know what to do if it does", with different degrees of seriousness. You basically want the application to "bomb out" of whatever it's doing at that moment. If essentially the application can go on working after the unexpected condition, throw a RuntimeException. Throw an InternalError in cases where "this is a very serious unexpected condition": the application is not expected to continue working and should shut down as soon and safely as possible. These exceptions are useful with the technique of recasting, where we turn a normal exception into another that represents a serious condition.

Many other exceptions are regular "checked" exceptions (see the exception hierarchy for more details), which means that if your method throws it, you will have to declare it with throws in the method signature:

public void processFile(File f) throws IOException {
  if (f.length() > MAX_LENGTH)
    throw new IOException("File too big");
  ...
}

Be careful not to confuse throw and throws!