[eclipse-pmc] API additions to JDT/Core

[Satyam Kandula <satyam.kandula@xxxxxxxxxx>]

JDT team want to add new APIs to JDT/Core in org.eclipse.jdt.core.JavaCore
and 
org.eclipse.jdt.core.compiler.IProblem. 

BACKGROUND:
===========
In M6, JDT/Core has extended the analysis of incomplete
switch statements 
on enum[1]. It started reporting warnings if 'default'
case is not provided. 
Post the M6 release, we have learned from users that
the solution 
conflicts with justified interests to get warnings
about incompleteness 
according to different criteria. This is perceived
as a regression over 3.7.x.

Any fix for this regression requires changes to API constants.

The JDT team (Core & UI) took the opportunity to extend the M6 solution
to a broader and more flexible approach [2], which also covers an old
outstanding bug [3] (marked WONTFIX during bulk-cleanup).

API CHANGES:
============
In class org.eclipse.jdt.core.JavaCore:
Change contract of this constant:
   COMPILER_PB_INCOMPLETE_ENUM_SWITCH [4]
Add these constants:
   COMPILER_PB_MISSING_ENUM_CASE_DESPITE_DEFAULT [5]
   COMPILER_PB_SWITCH_MISSING_DEFAULT_CASE [6]

In interface org.eclipse.jdt.core.compiler.IProblem:
Add these constants:
   MissingDefaultCase
   MissingEnumConstantCaseDespiteDefault
   UninitializedLocalVariableHintMissingDefault
   UninitializedBlankFinalFieldHintMissingDefault
   ShouldReturnValueHintMissingDefault

IMPACT:
=======
These changes are harmless because:
- Syntactically all these are additions of constants.
- Semantically only one constant is changed that was introduced
   only in M6, hence JDT/UI is most likely the only consumer
   that is affected by this change.


[1] https://bugs.eclipse.org/bugs/show_bug.cgi?id=265744
[2] https://bugs.eclipse.org/bugs/show_bug.cgi?id=374605
[3] https://bugs.eclipse.org/bugs/show_bug.cgi?id=132917
[4] Updated Javadoc for COMPILER_PB_INCOMPLETE_ENUM_SWITCH
        /**
       
 * Compiler option ID: Reporting Incomplete Enum Switch.
       
 * <p>When
enabled, the compiler will issue an error or a warning
       
 *              
  regarding each enum constant for which a corresponding
case label is lacking.
       
 *              
  Reporting is further controlled by the option {@link #COMPILER_PB_MISSING_ENUM_CASE_DESPITE_DEFAULT}.
       
 * <dl>
       
 * <dt>Option
id:</dt><dd><code>"org.eclipse.jdt.core.compiler.problem.incompleteEnumSwitch"</code></dd>
       
 * <dt>Possible
values:</dt><dd><code>{
"error", "warning", "ignore" }</code></dd>
       
 * <dt>Default:</dt><dd><code>"warning"</code></dd>
       
 * </dl>
       
 * @since
3.1
       
 * @category
CompilerOptionID
       
 */
     Modifications:
       3.7:
       
 * <p>When
enabled, the compiler will issue an error or a warning whenever
       
 *    an enum constant has no corresponding case
label in an enum switch
       
 *    statement.
       
 * ....

       
 * <dt>Default:</dt><dd><code>"ignore"</code></dd>
   
       3.8M6:
 
       
* <p>When
enabled, the compiler will issue an error or a warning whenever
       
 *    an enum switch statement lacks a default case.
       
 *    If no default case is given, additionally
one error or warning is issued
       
 *    regarding each enum constant for which a corresponding
case label is lacking.
       
* ....
       
* <dt>Default:</dt><dd><code>"warning"</code></dd>
       
       Proposed:
       
  * <p>When
enabled, the compiler will issue an error or a warning
       
 *              
  regarding each enum constant for which a corresponding
case label is lacking.
       
 *              
  Reporting is further controlled by the option {@link #COMPILER_PB_MISSING_ENUM_CASE_DESPITE_DEFAULT}.
       
 * ....
       
  * <dt>Default:</dt><dd><code>"warning"</code></dd>
       
 
[5] Javadoc for COMPILER_PB_MISSING_ENUM_CASE_DESPITE_DEFAULT

      /**
       
 * Compiler option ID: Reporting Missing Enum Case
In Switch Despite An Existing Default Case.
       
 * <p>This
option further controls the option {@link #COMPILER_PB_INCOMPLETE_ENUM_SWITCH}:
       
 *         <ul>
       
 *         <li>If
enabled the compiler will report problems about missing enum constants
even if a default case exists
       
 *              
  in the same switch statement.</li>
       
 *  <li>If
disabled existence of a default case is considered as sufficient to make
a switch statement complete.</li>
       
 *  </ul>
       
 *  This option has no effect if {@link #COMPILER_PB_INCOMPLETE_ENUM_SWITCH}
is set to <code>"ignore"</code>.
       
 * <dl>
       
 * <dt>Option
id:</dt><dd><code>"org.eclipse.jdt.core.compiler.problem.missingEnumCaseDespiteDefault"</code></dd>
       
 * <dt>Possible
values:</dt><dd><code>{
"enabled", "disabled" }</code></dd>
       
 * <dt>Default:</dt><dd><code>"disabled"</code></dd>
       
 * </dl>
       
 * @since
3.8
       
 * @category
CompilerOptionID
       
 */
[6] Javadoc for COMPILER_PB_SWITCH_MISSING_DEFAULT_CASE
        /**
       
 * Compiler option ID: Reporting Missing Default Case In Switch.
       
 * <p>When
enabled, the compiler will issue an error or a warning 
       
 *              
  against each switch statement that lacks a default case.
       
 * <dl>
       
 * <dt>Option
id:</dt><dd><code>"org.eclipse.jdt.core.compiler.problem.missingDefaultCase"</code></dd>
       
 * <dt>Possible
values:</dt><dd><code>{
"error", "warning", "ignore" }</code></dd>
       
 * <dt>Default:</dt><dd><code>"ignore"</code></dd>
       
 * </dl>
       
 * @since
3.8
       
 * @category
CompilerOptionID
       
*/