title: How to avoid deprecation warnings when @SuppressWarnings("deprecation") doesn't work?
body: <p>We have a Java project. We enable <code>-Xlint</code> (enable warnings) and <code>-Werror</code> (treat warning as error) flags for <code>javac</code>, to make sure our code is warning-free. Recently we decide to deprecate a class. The problem is in some cases <code>@SuppressWarnings("deprecation")</code> will not suppress the deprecation warning at all, resulting in build failure. Below is a list of use cases that I ran into:</p>
  
  <ol>
  <li>Imported in other non-deprecated classes.</li>
  <li>Imported in other deprecated classes.</li>
  <li>Parent class.</li>
  <li><p>Type parameter. For example</p>
  
  <pre><code>@SuppressWarnings("deprecation")
  public class Foo extends Bar&lt;DeprecatedClass&gt;
  { ... }
  </code></pre>
  
  <p>However, this one has no warning even without suppress:</p>
  
  <pre><code>@Deprecated
  public class DeprecatedClass extends Bar&lt;DeprecatedClass&gt;
  { ... }
  </code></pre></li>
  </ol>
  
  <p>AFAIK, there is no syntax for annotating imports, so for case 1 and 2 our solution is to either import * or avoid importing. For case 3 and 4, both Java 6 and 7 do not suppress the warning. Java 8 will correctly suppress it (maybe a bug is fixed). So far no solution for this.</p>
  
  <p>Unfortunately, we have to support Java 6, 7 and 8 at this point. Is there way to deal with the problem? It is a road block for our Java API evolution.</p>
  
  <p><strong>ADDENDUM</strong></p>
  
  <p>Many people ask why do we still use the deprecated class in our own codebase. The reason is that the project is a library, supporting many different clients. When introducing new replacement API, we have to first deprecate our old API, keep it in our codebase, wait for all clients to migrate then remove it. There are three common use cases:</p>
  
  <ul>
  <li>We deprecate class <code>Foo</code> and <code>Bar</code>, where <code>Foo</code> extends <code>Bar</code>. This is the case 2 and 3 in my question.</li>
  <li>We deprecate class <code>Foo</code> and <code>Bar</code>, where <code>Foo</code> extends <code>Collection&lt;Bar&gt;</code>. This is the case 2 and 4.</li>
  <li>We must keep all test code for class <code>Foo</code> and <code>Bar</code>. The test code imports these classes. This is the case 1.</li>
  </ul>
  
  <p>Why keep the test? Don't forget that if a serious bug (e.g. memory leak, security issue) is discovered, and the clients can't easily migrate to the new version, we still need to provide bug fix to the old API. And all changes must be tested.</p>
  
  <p>I feel our situation should be fairly common in software library development and API evolution. Surprisingly it took Java such long time (until Java 8) to fix the bug.</p>