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

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} */@Deprecatedpackage com.acme.old.package;

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

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.

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)