Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8065614 JEP 277: Enhanced Deprecation
  3. JDK-8157055

consider unified release notes for deprecated APIs

XMLWordPrintable

      Projects are now starting to notice deprecations in JDK 9 EA builds. The first wave of deprecation warnings is from the deprecation of the boxed constructors.

      One point to re-emphasize is that deprecation doesn't imply imminent removal unless forRemoval=true. There seems to be some different reactions to new deprecations. One is apparent urgency at fixing up warnings, as if the deprecated APIs are going to be removed shortly. Another is resistance to deprecation because of the amount of work generated. Cleaning up warnings is a certain amount of work, but it might be that this is magnified by the assumption that the APIs will be removed (or be made "unstable") by the deprecation, which isn't true in most cases.

      There are some pitfalls in removing these warnings by editing the source code. There should be a recommendation about a set of steps to take. For example, for the box constructor deprecations:

      1) Disable deprecation warnings using -Xlint:-deprecation. Deprecation warnings are rarely the most important thing to deal with in migrating to JDK 9. This is only a temporary workaround, of course, but dealing with warnings needn't be in the critical path of migration.

      2) Suppress warnings with @SuppressWarnings("deprecation"). This is useful at particular call sites that use the box constructors. This does add clutter to the code, but it's called for in certain uncommon cases where the code really does want to use a box constructor instead of an alternative. These cases are typically where the identity of a boxed value is significant, for example, if they are compared using == or !=, or if they are stored in an IdentityHashMap.

      We are also considering other mechanisms for finer-grained warnings control.

      3) Replace the constructor call with a call to valueOf(). For example, instead of new Integer(x), call Integer.valueOf(x). This is the safest transformation, since it avoids pitfalls with autoboxing and overload resolution. It doesn't preserve identity semantics, though, as noted above.

      4) Converting to autoboxing is often safe but there are a number of "gotchas." For example, if 'list' is a List<Integer>, and 'x' is an int, then
          list.remove(new Integer(x))
      must not be changed to
          list.remove(x)
      because this changes overload resolution so that List.remove(int) is called instead of List.remove(Object).

      ==========

      In addition to enhancements to deprecation itself, the release notes should also cover features, APIs, and packages that have been deprecated. Issues relating to deprecation of those should be linked to this subtask.

            smarks Stuart Marks
            smarks Stuart Marks
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: