What is the clearest way to deprecate a package in Java?

Question

I\'m working on a new codebase and migrating the system to a new framework.

There are a number of packages that I would like to deprecate, just to make it very clear

Answer 1

As mentioned by @muymoo before, you could use a package-info.java file. But all you can do is add a @deprecated warning in the JavaDoc of your file:

/**
 * @deprecated This package is deprecated, use {@link my.new.pkg} instead.
 */
package my.old.pkg;

JavaDoc is really your only option here, you cannot @Deprecate the package using a "proper" in-code annotation

@Deprecated
package my.old.pkg;

will lead to a compilation error in Java 8

$ java -version
java version "1.8.0_191"

$ javac package-info.java
package-info.java:6: error: modifier deprecated not allowed here

The only real, clean option here is to really deprecate all the classes in your package. Which does make sense, if you think about it, because a package in Java is nothing more then a namespace.

Answer 2

I had to do this recently and used the package-info.java file to deprecate the package.

http://www.intertech.com/Blog/whats-package-info-java-for/

Add a package-info.java file to your package with only the package declaration:

/**
 * @deprecated As of release 2.0, replaced by {@link com.acme.new.package}
 */
@Deprecated
package com.acme.old.package;

In Eclipse, all places where the user imports a class from this package will be underlined with a deprecation warning.

Answer 3

Use AspectJ. Create an Aspect that issues a compiler warning when the package is used:

public aspect DeprecationAspect{

    declare warning :
        call(* foo.bar..*(..)) : "Package foo.bar is deprecated";

}

(You can easily add AspectJ to your build if you use ant or maven)

Answer 4

For those who came later...
My solution with IDEA "Replace in Path"

Text to find: (public|protected)+(\s)(abstract)(\s)(static)(\s)(final)(\s)*(class|interface|enum|Enum)
Replace with: @Deprecated\n\$1 \$3 \$5 \$7 \$9
Options: (select) Regular expressions
Directory: {Choose dir}

Answer 5

You said it yourself: You want to deprecate everything that's inside a package, not the package itself. The package is nothing but a namespace and deprecating a namespace would have a different meaning - like don't use this namespace anymore. Like don't add any new items to that namespace.

In your case, I suggest you deprecate each public method (and field) of each class that shouldn't be used anymore. This becomes visible in modern IDE's and developers are warned when they want to use the old classes and methods. And you can look through your code and refactor it step by step to eliminate dependencies of those classes and methods.

Answer 6

You can create Package annotation and deprecate any package with @Deprecated :)