Core Java

Exceptions, Assertions, and Logging

Slide navigation: Forward with space bar, → arrow key, or PgDn. Backwards with ← or PgUp.

Use exceptions to report errors in a program

Dealing with Errors

• When an error occurs, your program can:
  • Return to a safe state and allow the user to execute other commands.
  • Save the user's work and terminate.
• What kind of errors do you need to consider?
  • User input errors.
  • Device errors and physical limitations.
  • Code errors.
• What can you do when an error occurs?
  • Return an error code.
  • Terminate the program.
  • Throw an exception.

The Classification of Exceptions

• Errors are internal problems: exhaustion of memory or other resources.
• Runtime exceptions are the programmer's fault: null pointers, out of bounds values, and so on.
• Other exceptions are unavoidable facts of life: flaky network connections, files that were just moved, and so on.

except

Declaring Checked Exceptions

• The “facts of life” exceptions are checked exceptions: The compiler checks that you deal with them.
• These are subclasses of Exception but not of RuntimeException.
• If you write a method that might throw such an exception, you need to declare that fact.
• Add a throws clause:

  public Image loadImage(String s) throws IOException

• A throws clause can list multiple exceptions:

  public Image loadImage(String s) throws FileNotFoundException, EOFException

• Don't declare unchecked exceptions:

  void drawImage(int i) throws ArrayIndexOutOfBoundsException // bad style

  Instead, fix your code so that this doesn't happen!

Throwing Exceptions

• Suppose something terrible happened in your code. You read a header that promised Content-length: 1024, but you got an end of file after 733 characters.
• Find an exception type to throw.
  • The Java library has an EOFException with description: “Signals that an EOF has been reached unexpectedly during input.”
• Construct an object and throw it:

  throw new EOFException();

• Or better, provide a reason:

  String gripe = "Content-length: " + len + ", Received: " + n;
  throw new EOFException(gripe);

Creating Exception Classes

• What if your situation isn't covered by an exception in the standard library?
• Create your own exception class.
• Subclass Exception, RuntimeException, or preferably a more specific exception class:

  class FileFormatException extends IOException
  {
     public FileFormatException() {}
     public FileFormatException(String gripe) { super(gripe); }
  }

• Then you can throw an object of your own exception type:

  if (n < len) throw new FileFormatException();

Catch exceptions to remedy error conditions

Catching an Exception

• If an exception is thrown, and nobody catches it, your program terminates.
• Use a try/catch block to catch an exception:

  try
  {
     code
     more code
     more code
  }
  catch (ExceptionType e)
  {
     handler for this type
  }

• Only do this if you can actually do something useful when the exception occurs.
• There is no shame in propagating exceptions.
• Exception: Sometimes you need to catch an exception when you override a method that is declared to throw no checked exceptions.

Catching Multiple Exceptions

• You can catch multiple exceptions in separate catch clauses:

  try
  {
     code that might throw exceptions
  }
  catch (FileNotFoundException | UnknownHostException e)
  {
     emergency action for missing files and unknown hosts
  }
  catch (IOException e)
  {
     emergency action for all other I/O problems
  }

• Work with the inheritance hierarchy of exceptions: Catch more specific exceptions before more general ones.

Rethrowing and Chaining Exceptions

• Sometimes you want to catch an exception and rethrow it as a different type:

  try
  {
     access the database
  }
  catch (SQLException e)
  {
     throw new ServletException("database error: " + e.getMessage());
  }

• Better: Set the original exception as the cause.

  ...
  catch (SQLException e)
  {
     Throwable se = new ServletException("database error");
     se.initCause(e);
     throw se;
  }

• The cause can later be retrieved with the getCause method.

The finally Clause

• Suppose your code accesses a resource that needs to be relinquished:

  PrintWriter out = new PrintWriter(...);
  . . .
  out.close();
  

• What if the . . . code throws an exception?
• The out.close() statement is never executed!
• Remedy: Put it in a finally clause:

  PrintWriter out = new PrintWriter(...);
  try
  {
     . . .
  }
  finally
  {
     out.close();
  }
  

The Try-with-resources Statement

• The pattern “open a resource/close it in all cases” is very common.
• Useful shortcut:

  try (Resource res = . . .)
  {
     work with res
  }

• The Resource class must implement the AutoCloseable interface, which has a single method:

  void close() throws Exception

• You can specify multiple resources:

  try (Scanner in = new Scanner(Paths.get("in.txt"), "UTF-8");
     PrintWriter out = new PrintWriter("out.txt"))
  {
     while (in.hasNext())
        out.println(in.next().toUpperCase());
  }
  

• Correctly handles all the tricky issues: What if the try block throws an exception, and so does one of the close methods?

The Stack Trace

• When an exception terminates a program, a stack trace is displayed.
  • List of pending method calls.
• You can print the stack to the error stream:

  catch (Exception e) { e.printStackTrace(); }
  

• To save to a string, do this:

  StringWriter out = new StringWriter();
  e.printStackTrace(new PrintWriter(out));
  String description = out.toString();

• You can analyze stack traces programmatically:

  StackTraceElement[] frames = e.getStackTrace();
  for (StackTraceElement frame : frames) ...

• Can trap exception reports in GUI programs:

  Thread.setDefaultUncaughtExceptionHandler((Thread t, Throwable e) -> ...);
  

stackTrace

Java 9 News Flash - try Blocks

• try-with-resources can be used with an effectively final variable:

  void print(PrintWriter out, String[] lines) {
      try (out) { // Effectively final variable
          for (String line : lines) 
              out.println(line.toLowerCase());
      }
  }

• Note that out was not declared in the try block.
• For a parameter, be sure to document that it will be closed.

Know how to use exceptions effectively

exceptional

Tips for Using Exceptions

• Exception handling is not supposed to replace a simple test.

  try { s.pop(); } catch (EmptyStackException e) { }

  ⇒

  if (!s.empty()) s.pop();

• Do not micromanage exceptions.

  for (i = 0; i < 100; i++) { try { n = s.pop(); } catch (EmptyStackException e) { . . . } try { out.writeInt(n); } catch (IOException e) { . . . } }

  ⇒

  try { for (i = 0; i < 100; i++) { n = s.pop(); out.writeInt(n); } } catch (IOException e) { . . . } catch (EmptyStackException e) { . . . }

Tips for Using Exceptions

• Make good use of the exception hierarchy:
  • Don’t just throw a RuntimeException. Find an appropriate subclass or create your own.
  • Don’t just catch Throwable.
  • Respect the difference between checked and unchecked exceptions.
  • Do not hesitate to turn an exception into another exception that is more appropriate.
• Do not squelch exceptions:

  try
  {
     code that threatens to throw checked exceptions
  }
  catch (Exception e)
  {} // so there

Tips for Using Exceptions

• When you detect an error, “tough love” works better than indulgence.
  • When something is very wrong, throw an exception.
  • Don't return an error code or a dummy value.
  • Return values must be handled by the caller. Exceptions can be handled anywhere upstream.
• Propagating exceptions is not a sign of shame.
  • Don't try to handle an exception that you can't remedy.
  • Just let it be rethrown so that it can reach a competent handler.
• These two rules can be summarized as: “throw early, catch late.”

Use assertions to enforce algorithm constraints

The Assertion Concept

• Sometimes, your code assumes that a particular property is fulfilled.
• Example—Compute

  double y = Math.sqrt(x);

  You are certain that x is not negative.
• What if it is? You can provide a check:

  if (x < 0) throw new IllegalArgumentException("x < 0");

• But if you are right, this code stays in the program even after testing is complete, and it slows down your program.
• An assertion provides a test that you can turn off:

  assert x >= 0;

  When assertions are enabled, an AssertionError is thrown.
• You can pass a message, or an object that is stringified into a message:

  assert x >= 0 : x;
  

Assertion Enabling and Disabling

• By default, assertions are disabled.
• Enable them like this:

  java -enableassertions MyApp

• You don't have to recompile. Assertions are handled as classes are loaded.
• You can enable or disable assertions on a per-class or per-package basis:

  java -ea:MyClass -ea:com.horstmann.corejava -da:AnotherClass MyApp

When to Use Assertions

• Use assertions for checking parameters:
  • Suppose a method clearly states: a must not be null.
  • Then it is fair to add assert a != null;
  • If a is null, the program is aborted with a clear error...
  • ...provide assertions are enabled.
  • Assertions are intended to terminate a program, not for recovery.
• Use assertions for checking assumptions:
  • Example from Java tutorial:

  • if (i % 3 == 0) . . .
    else if (i % 3 == 1) . . .
    else
    {
       assert i % 3 == 2;
       . . .
    }

  • Of course, it would make even more sense to think through the issue:

    assert i >= 0;

Use logging to record what your program does

Advantages of the Logging API

• Better than inserting System.out.println calls.
• Can suppress reports below a given log level.
• Log records can be directed to different handlers: console, file, ...
• Loggers and handlers can filter records.
• Log records can be formatted in different ways: plain text, XML, ...
• Applications can use a hierarchy of loggers.
• Logging configuration controlled by a configuration file.

Logging 101

• Use the global logger and call its info method:

  Logger.getGlobal().info("File->Open menu item selected");

• By default, the record is printed like this:

  May 10, 2013 10:12:15 PM LoggingImageViewer fileOpen
  INFO: File->Open menu item selected

• To suppress messages, call:

  Logger.getGlobal().setLevel(Level.OFF);

Loggers

• Use your own logger:

  private static final Logger myLogger = Logger.getLogger("com.mycompany.myapp");

• This way, the logger doesn't get garbage collected.
• Loggers are hierarchical.
  • com.mycompany.myapp inherits log settings on the com.mycompany logger.

Levels

• Log levels: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST
• Set level like this:

  logger.setLevel(Level.FINE);

• Methods for all levels:

  logger.warning(message);
  logger.fine(message);
  logger.log(Level.FINE, message);

• Caution: To see levels finer than INFO, you need to change the log handler configuration.

Logging Program Flow

• Convenience methods for tracking execution flow:

  int read(String file, String pattern)
  {
     logger.entering("com.mycompany.mylib.Reader", "read",
        new Object[] { file, pattern });
     . . .
     logger.exiting("com.mycompany.mylib.Reader", "read", count);
     return count;
  }

• Log exception throwing and catching:

  IOException exception = new IOException(". . .");
  logger.throwing("com.mycompany.mylib.Reader", "read", exception);
  throw exception;
  ...
  catch (IOException e)
  {
     logger.log(Level.WARNING, "Reading image", e);
  }
  

Configuration

• Default (system-wide) configuration file: jre/lib/logging.properties
• Can set other file at program startup:

  java -Djava.util.logging.config.file=configFile MyProg

• To change the default logging level, use configuration:

  .level=INFO

• Configure your own loggers:

  com.mycompany.myapp.level=FINE

• Caution: These settings are not system properties.
• Can also set up log file location and rotation.
• Can change log levels in a running program with the jconsole tool.

Handlers

• By default, log records are sent to a ConsoleHander instance.
  • Displayed on System.err
• Handlers also have a level.
  • Default configuration:

    java.util.logging.ConsoleHandler.level=INFO

• Logger sends records to its own handler and parent handlers.
  • Primordial logger sends records to console.
  • Call logger.setUseParentHandlers(false) to turn off.
• Send records to a file:

  FileHandler handler = new FileHandler();
  logger.addHandler(handler);

• Records are saved in javan.log in home directory.
• Default format is XML.
• Override in log configuration:

  java.util.logging.FileHandler.pattern=%h/myapp%u.log

logging