CSC 224 Lecture Notes

• Errors occur in software programs.
• But what really matters is what happens after the error occurs.
  • How is the error handled?
  • Who handles it?
  • Can the program recover, or should it just die?

• An exceptional event
• Exceptions to normal behavior
  • Situations where the unexpected happens
  • Not preventable since not predictable
• Sources of exceptional situations
  • User input, e.g. file names, URLs, DBs, etc.
  • Hardware and network problems
  • Invalid arguments to methods (e.g. indices)
• An exception is an event that occurs during the execution of a program that disrupts the normal flow of instructions.

• Allows graceful recovery from errors
• Using certain Java methods requires it
  • Methods can throw Exception objects
    • Instead of returning normally
  • Compiler complains if exception not handled
• Separates normal logic from exceptions
  • Write "perfect world" code w/o lots of ifs
  • Handle exceptions only when they occur

Advantage 1: Separating Error Handling Code from "Regular" Code

pseudocode:

readFile {
    open the file;
    determine its size;
    allocate that much memory;
    read the file into memory;
    close the file;
}

At first glance this function seems simple enough, but it ignores all of these potential errors:

• What happens if the file can't be opened?
• What happens if the length of the file can't be determined?
• What happens if enough memory can't be allocated?
• What happens if the read fails?
• What happens if the file can't be closed?

Your function would end up looking something like this:

errorCodeType readFile {
    initialize errorCode = 0;
    open the file;
    if (theFileIsOpen) {
        determine the length of the file;
        if (gotTheFileLength) {
            allocate that much memory;
            if (gotEnoughMemory) {
                read the file into memory;
                if (readFailed) {
                    errorCode = -1;
                }
            } else {
                errorCode = -2;
            }
        } else {
            errorCode = -3;
        }
        close the file;
        if (theFileDidntClose && errorCode == 0) {
            errorCode = -4;
        } else {
            errorCode = errorCode and -4;
        }
    } else {
        errorCode = -5;
    }
    return errorCode;
}

versus the Java style:

readFile {
    try {
        open the file;
        determine its size;
        allocate that much memory;
        read the file into memory;
        close the file;
    } catch (fileOpenFailed) {
        doSomething;
    } catch (sizeDeterminationFailed) {
        doSomething;
    } catch (memoryAllocationFailed) {
        doSomething;
    } catch (readFailed) {
        doSomething;
    } catch (fileCloseFailed) {
        doSomething;
    }
}

Advantage 2: Propagating Errors Up the Call Stack

Old style:

method1 {
    call method2;
}
method2 {
    call method3;
}
method3 {
    call readFile;
}

Suppose that method1 is the only method interested in the errors that occur within readFile. Traditional error notification techniques force method2 and method3 to propagate the error codes returned by readFile up the call stack until the error codes finally reach method1

method1 {
    errorCodeType error;
    error = call method2;
    if (error)
        doErrorProcessing;
    else
        proceed;
}
errorCodeType method2 {
    errorCodeType error;
    error = call method3;
    if (error)
        return error;
    else
        proceed;
}
errorCodeType method3 {
    errorCodeType error;
    error = call readFile;
    if (error)
        return error;
    else
        proceed;
}

Java style:

method1 {
    try {
        call method2;
    } catch (exception) {
        doErrorProcessing;
    }
}
method2 throws exception {
    call method3;
}
method3 throws exception {
    call readFile;
}

Advantage 3: Grouping Error Types and Error Differentiation

-Exceptions are first-class objects in Java
-Allowing for better error handling depending on the specifications of the particular error, which can be very unique, and even more so if you define your own.
-For example, in the following diagram, ArrayException is a subclass of Exception (a subclass of Throwable) and has three subclasses.

-InvalidIndexException, ElementTypeException, and NoSuchElementException are all leaf classes. Each one represents a specific type of error that can occur when manipulating an array.
-You can have a catch statement for each one of them

1. A method throws an exception
2. the runtime system leaps into action to find someone to handle the exception
   • The set of possible "someones" to handle the exception is the set of methods in the call stack of the method where the error occurred
3. The runtime system searches backwards through the call stack, beginning with the method in which the error occurred, until it finds a method that contains an appropriate exception handler.
   • appropriate if the type of the exception thrown is the same as the type of exception handled by the handler.
   • The exception handler chosen is said to catch the exception.
4. If the runtime system searches all of the methods on the call stack without finding an appropriate exception handler, the Java program terminates.

• Root class of exceptions: Throwable
  • Error deals with internal errors/resources
• Subclasses of Exception class
  • RunTimeException (unchecked exceptions)
    • e.g. casting errors, array index errors, null pointers (your fault)
  • Other subclasses (checked exceptions), e.g.
    • IOException - problems with I/O operations
    • SQLException - problems with SQL statements
    • The Java language requires that a method either catch all "checked" exceptions (those that are checked by the runtime system) or specify that it can throw that type of exception.

• Exceptions are like any other objects
• Extend Exception (or a subclass of it)
  • Provide constructors to build exception object
  • Store data about exception, if necessary
  • Provide any desired accessor methods class MyOwnException extends Exception { public MyOwnException(String m, int n) { super(m); errorNo = n; } private int errorNo; // plus get method }

• Declare throwing of checked exceptions
  • e.g. public int myMethod(String s) throws MyOwnException { ... }
• Create appropriate exception object
• Send exception to caller using throw ... if (somethingWentWrong()) throw new MyOwnException("This is what when wrong...", 17); ...// code here not done if exception was thrown

• A method call throws exception X
  • Nothing you can do about the problem?
    • Declare your method as throwing exception X
  • Otherwise, handle the exception yourself
• Something is wrong with passed arguments
  • Throw exception if unable to perform task
    • i.e. if no default behavior makes sense

• Exception classes have normal inheritance
  • Subclass allowed where superclass expected
• Using exceptions in subclass vs. superclass
  • Subclass method cannot have more exceptions
    • Can throw less by handling superclass exceptions
    • Must handle new exceptions in overridden methods
  • Reason: upcasting from subclass to superclass
    • Have to know what exceptions are possible

• The try/catch block
  try
{ some code that might throw exceptions
} catch (SomeException e)
{ code to deal with exception }

  • Code in try is run until exception (if any)
  • Matching catch run or exception propagated
• What happens with uncaught exceptions?
  • Console program ends; error on console (GUI)

• Handle all exceptions that you can sensibly
• If there’s nothing sensible that you can do:
  • Propagate exception as-is to caller of method
    • i.e. do not have a catch clause for exception
    • Must declare that your code throws exception
  • Or, do what you can and re-throw exception
• Must declare that your code throws exception

• Need to run certain clean-up code
  • Some try code not run, leaving invalid state
  • Uncaught exception exits method immediately
    • No opportunity to get to normal clean-up code
• Solution: put code in finally clause
  • Always executed, after try or catch code
  • Whether or not exception is thrown or caught
  • Done before exit for uncaught exceptions

1. Is the following code legal?

   try {
       ...
   } finally {
       ...
   }
   

2. What exception types can be caught by the following handler?

   catch (Exception e) {
       ...
   }
   

   What is wrong with using this type of exception handler?

3. What exceptions can be caught by the following handler?

   ...
   } catch (Exception e) {
       ...
   } catch (ArithmeticException a) {
       ...
   }
   

   Is there anything wrong with this exception handler as written? Will this code compile?

4. What will be returned below?

   try {
       return 2;
   } finally {
       return 3;
   }
   

1. Question: Is the following code legal?

   try {
       ...
   } finally {
       ...
   }
   

   Answer: Yes, it's legal. A try statement does not have to have a catch statement if it has a finally statement. If the code in the try statement has multiple exit points and no associated catch clauses, the code in the finally statement is executed no matter how the try block is exited.

2. Question: What exception types can be caught by the following handler?

   catch (Exception e) {
       ...
   }
   

   What is wrong with using this type of exception handler?

   Answer: This handler catches exceptions of type Exception; therefore, it catches any exception. This can be a poor implementation because you are losing valuable information about the type of exception being thrown and making your code less efficient. As a result, the runtime system is forced to determine the type of exception before it can decide on the best recovery strategy.

3. Question: What exceptions can be caught by the following handler?

   ...
   } catch (Exception e) {
       ...
   } catch (ArithmeticException a) {
       ...
   }
   

   Is there anything wrong with this exception handler as written? Will this code compile?

   Answer: This first handler catches exceptions of type Exception; therefore, it catches any exception, including ArithmeticException. The second handler could never be reached. This code will not compile.

4. Question: What will be returned below?

   try {
       return 2;
   } finally {
       return 3;
   }
   

   Answer: 3, the try will complete correctly, but before any value is actually returned, finally will run and its return statement will be returned.

• javadoc parses the declarations and documentations in a set of Java source files and generates API documentation in HTML
• pulls out the important information concerning the classes, inner classes, interfaces, constructors, methods, and fields, and automatically generates good-looking documentations.
• The feature is not duplicated in any other languages, and the great advantage of this approach is keeping the documentation up-to-date.
• You can run javadoc on entire packages, individual source files, or both.
  • javadoc *.java
  • javadoc produces one complete document each time it is run; it cannot do incremental builds
    • it cannot modify or directly incorporate results from previous runs of javadoc.
    • However, it can link to results from previous runs
  • The text covered javadoc back on page 173
  • http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html.

• Text intended for javadoc must be placed in doc-comments that begin with /** and end with */.

• Doc-comments for a class or method must be placed immediately before the class or method declaration.

• The first sentence for a doc-comment should be a one-sentence summary of the class or method being documented.

• javadoc parses special tags that are recognized when they are embedded within a Java doc-comment. 
• These doc tags enable you to autogenerate a complete, well-formatted API from your source codes. The tags start with an "at" sign (@) and are case-sensitive.

@author  name-text

Creates an "Author" entry.  A doc comment may contain multiple @author tags.

@deprecated  deprecated-text

Adds a deprecated comment indicating that this API should not use the specified features of the class. Deprecated notes normally appear when a class has been enhanced with new and improved features, but older features are maintained for backwards compatibility.

@exception  class-name description

The @exception tag is a synonym for @throws.

{@link  name  label}

This tag allows the programmer to insert an explicit hyperlink to another HTML document.

@param  parameter-name description

Adds a parameter to the "Parameters" section. The description may be continued on the next line.

@return  description

Adds a "Returns" section, which contains the description of the return value.

@see  reference

Adds a "See Also" heading with a link or text entry that points to reference.

@serial  field-description

Used in the doc comment for a default serializable field.

An optional field-description augments the doc comment for the field. The combined description must explain the meaning of the field and list the acceptable values.

@serialData  data-description

A data-description documents the sequences and types of data, specifically the optional data written by the writeObject method and all data written by the Externalizable.writeExternal method. The @serialData tag can be used in the doc comment for the writeObject, readObject, writeExternal, and readExternal methods.

@serialField  field-name  field-type  field-description

Documents an ObjectStreamField component of a Serializable class' serialPersistentFields member. One @serialField tag should be used for each ObjectStreamField component.

@since  since-text

Adds a "Since" heading with the specified since-text to the generated documentation. These notes are used for new versions of a class to indicate when a feature was first introduced. For example, the Java API documentation uses this to indicate features that were introduced in Java 1.0, Java 1.1 or Java 2.

@throws  class-name  description

The @throws and @exception tags are synonyms. Adds a "Throws" subheading to the generated documentation, with the class-name and description text. The class-name is the name of the exception that may be thrown by the method. If this class is not fully-specified, javadoc uses the search order to look up this class.

@version  version-text

Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used. The text has no special internal structure. A doc comment may contain at most one @version tag. Version normally refers to the version of the software (such as the JDK) that contains this class or member.

• For a class defined in the file ClassName.java, javadoc generates a documentation file named ClassName.html
• The file will be well hyperlinked and will look exactly like the standard API
• Links all your classes together