Exception-throwing compatibility

There are a number of methods in the Java specification that describe the conditions under which exceptions are thrown. However, in most cases the specification does not describe all possible exceptions that may be thrown, the order of exception throwing (i.e. where there are multiple conditions that would result in an exception), and so on.

The Harmony class libary code aims to be fully compatible with the Reference Implementation (RI) of the Java Specification by matching the exception characteristics of each method.

Harmony classlib developers write test cases that deliberately cause exceptions to be thrown so that we can match exception behaviour like-for-like. Harmony class library code throws exceptions of the same runtime class (or a subtype of that runtime class) as the RI, other than in cases where the RI throws non-public types whereupon Harmony will throw an exception with the same public supertype.

Generally, we could refer to the following steps.

• If RI is compliant with the Java Specification
  We shall follow RI's behavior, that is, throws exactly the same exception or a subclass of the exception.
  • But there are some cases that RI throws an implementation specific exception, which is not in the Java Specification, we shall throw an equivalent Harmony specific exception, or its superclass in the Java Specification.
    e.g., If RI throws sun.io.MalformedInputException, we could throw org.apache.harmony.io.MalformedInputException or java.io.CharConversionException.
    
• If RI is not compliant with the Java Specification
  • If the Java Specification describes the exceptional situation explicitly, and RI throws different kind of exception or even does not throw any exception, we shall discuss them case by case in harmony-dev mailing list.
    • If we decide to follow RI, we will raise an "Non-bug differences from Spec" JIRA.
    • If we decide to follow Spec, we will raise an "Non-bug differences from RI" JIRA.
  • If the Java Specification does NOT describe the exceptional situation explicitly, and RI's behavior is either hard to reproduce or illogical, we shall discuss them case by case. We can
    • Follow RI
    • Follow Spec
    • Implement the functions in our own way.