Changes Between the Original Proposal and the Public Draft



I. Introduction

  1. Removed the statement that "It is not, in general, possible for the compiler to enforce a prohibition on side-effects in assertions." It was pointed out that with sufficient modifications to the language, a compiler might be able to enforce such a prohibition. A similar change was made to the statement regarding the use of assertions for argument checking.

II. Syntax

  1. Eliminated the required parentheses from the first form of the call, for consistency with the return and throw statements. Of course, parentheses can still be used if desired. Parentheses are still required in the second form.
  2. Eliminated the restriction in the second form of the assert statement that the the second expression must have a reference type. There was no compelling reason for this restriction, and removing it provides added convenience, e.g., for developers who want to associate a unique integer code with each assertion.
  3. Added subscripts to the expressions in the grammar to clarify exposition.

III. Semantics

  1. If the evaluation of the second ("detail message") expression in the two-expression form of the assert statement causes an exception to be thrown, this exception will not be caught, but will propagate outward. This was previously the case for the first (boolean) expression, but not the second. The change was made to simplify the semantics of the call and increase their consistency.
  2. The second expression in the second form of the assert statement is converted to a string as per JLS Section to allow for primitive and null values. This semantics change corresponds to syntax change II.2.
  3. The semantics was tightened up, and an effort was made to ensure that the style was similar to that of the other execution specifications in the JLS.

IV. Enabling and Disabling Assertions

  1. Renamed setAssertionStatus(String className, boolean enabled) to setClassAssertionStatus(String packageName, boolean enabled) and setDefaultAssertionStatus(String className, boolean enabled) to setPackageAssertionStatus(String className, boolean enabled). The new names are less confusing, as they do not rely on overloading.
  2. The setClassAssertionStatus method no longer throws an exception if the specified class has already been loaded. Instead, it returns a boolean value allowing the caller to determine whether the class will have (or already has) the desired assertion status. This behavior makes the method easier to use, especially in the case of low-level system classes, for which it is hard to predict whether they've already been loaded.
  3. Modified specification of setClassAssertionStatus(String className, boolean enabled) to indicate that the named class must be a top-level class. The nested-class granularity in previous drafts was judged not to be useful. Further, the implementation in Appendix IV did not work for nested classes.
  4. The method originally named setDefaultAssertionStatus(String, boolean) (now named setPackageAssertionStatus(String, boolean)) was erroneously specified to return a boolean value. The return type has been changed to void.
  5. Modified setPackageAssertionStatus method to provide support for "package trees." This allows assertions to be enabled easily in complex software systems consisting of multiple packages (e.g., Swing).
  6. Clarified specification for setPackageAssertionStatus to indicate how to modify the package default assertion status for the unnamed package that is "current" (JLS 7.4.2). Previously, it was not clear how to do this, and this functionality is clearly useful.
  7. Clarified specifications of setPackageAssertionStatus, setClassAssertionStatus and desiredAssertionStatus to specify what constitutes an illegal class or package name.
  8. Documented IllegalArgumentException for all ClassLoader methods that take a string argument. It is generally a good thing to document the unchecked exceptions that a method may throw.
  9. Clarified specification to indicate that all assertion status setting methods are instance methods on ClassLoader.
  10. Added specification for desiredAssertionStatus method. This method may be of little value to programmers but it greatly simplifies the implementation of the facility. This method was previously discussed in the "Implementation Notes" section.
  11. Enlarged the discussion of anonymous classes to apply to all "unnamable" classes. Other such classes (e.g., local classes) were not addressed by the original specification.

V. New Error Class

  1. Removed clazz, file, line and method arguments from constructor, and removed corresponding accessors from the class. This functionality will be "moved up the hierarchy" to Throwable, and will not require the information to be passed into the constructor. It was decided that this functionality was too useful to be restricted to assertion errors. Further, it partially duplicated the functionality of stack traces, which are available for any Throwable.
  2. Added an AssertionError constructor that takes a detail message. This constructor was unintentionally omitted from the original proposal.
  3. Added doc comment for class AssertionError. This comment was unintentionally omitted from the original proposal.

Appendix I. Usage Notes

  1. Added this non-normative appendix discussing uses of the facility.

Appendix II. Enabling and Disabling Assertions in the Interpreter

  1. Added this non-normative appendix describing the facilities that an interpreter might provide to allow assertions to be enabled and disabled. This material was previously contained in Section IV. It was moved in order to segregate all non-normative material in appendices.
  2. Modified -ea and -da descriptions to use ellipsis ("...") in place of asterisk ("*"), to eliminate the need for quoting the flag argument in most shells. This also emphasizes the difference in semantics between this string and the one that occurs in the import declaration. (The former refers to a package tree, while the latter refers to a single package.)
  3. Clarified specification of -ea switch to indicate how to enable the package default assertion status for the unnamed package that is "current". This is the interpreter analogue of IV.6.
  4. The default assertion status for the class loader was erroneously implied to be "enabled" when describing the command line switches. The specification was clarified to say that assertions are disabled by default in the interpreter.
  5. Added cautionary note concerning the presence of multiple class loaders. The interpreter must be careful to enable or disable assertions on the correct class loader.

Appendix III. Source Compatibility

  1. Added this non-normative appendix describing a strategy whereby compiler writers can allow developers to continue using existing programs that use assert as an identifier.

Appendix IV. Implementation Notes

  1. Modified the initialization of the synthetic field ($assertionsEnabled) to reflect the fact that desiredAssertionStatus is an instance method. (This was simply a bug in the original code.)
  2. Moved the specification for desiredAssertionStatus(className) to Section IV. It was decided that it was better to add this function to the public API, rather than to invoke it via some form of "black magic."
  3. Added String.valueOf call to the "equivalent code expansion" for the assertion statement. This is necessary to support primitive and null values.
  4. Added do-while loop to "equivalent code expansion," along with explanation of its purpose. (It causes the equivalent code to have the proper syntactic category, StatementWithoutTrailingSubstatement.)

Appendix V. Design FAQ

  1. Added this non-normative appendix to serve as a design rationale.

Miscellaneous Changes

  1. Added section numbers, as befits a specification.
  2. Eliminated "Open Issues" section.