Geertjan is a DZone Zone Leader and has posted 468 posts at DZone. You can read more from them at their website. View Full User Profile

@Transformation: Code Transformation Annotation

  • submit to reddit

When marking code as deprecated, wouldn't it be cool if you could provide instructions for how the code should be correctly fixed? Jaroslav Tulach and Jan Lahoda from the NetBeans Team have started a new open source project at for exactly that purpose.

To gain an instant understanding of what their project entails, look at this code:

public class Component extends Object {
displayName="Use setVisible(true)",
@Constraint(variable="$0", type=Window.class),
public void show() {

What you should see in the above code is... new annotations that supplement the @Deprecated annotation with additional annotations that provide the corrected code. Why is this useful? The project's page presents the problem statement thusly:

Using @Deprecated annotation is good hint to help your API users recognize that some part of your API is obsolete and shall no longer be used. However will your users really migrate? Will they invest their time to beautify their code without really making it work better? Usually the users have plenty other and more important things to do. The only chance for removal of uses of @Deprecated code is to make the rewrite process as automatic as possible.

In other words, if you don't do something to HELP your users upgrade, there's a good chance that they won't do so, since there are no feature benefits to be gained from migrating deprecated code. One simply achieves compliance, which is not typically the top of the list in a busy development schedule.

The @Transformation annotation is intended to be processed by an IDE, as follows for the code above, here in the case of NetBeans IDE:

 And here is another example, this time for a deprecated NetBeans API class:

Of course, the above show how the new annotations are processed in NetBeans IDE. It would be very cool if plugins were to be created for the other IDEs to process these annotations too. And that's why Jaroslav and Jan are wondering whether... anyone out there from IntelliJ IDEA or Eclipse would like to create similar support for those IDEs too? The related library of annotations is really small and manageable, as can be seen here:

If interested in being involved in this project in any way, please join at!

fig.png11.08 KB
fig-1.png9.01 KB
Published at DZone with permission of its author, Geertjan Wielenga.


Michael Bien replied on Mon, 2008/11/10 - 12:58pm

interesting. Looks like jackpot 2.0 ;) But please collapse those transformation annotations by default, this is not what I want to see if I browse through new APIs ;)


Osvaldo Doederlein replied on Mon, 2008/11/10 - 1:15pm

It's a good idea. These annotations are complex but they could easily be generated by the IDE's refactorings.

Eclipse already does that, except that it generates XML files which are automatically stored in the project's metadata and can be versioned and 'applied' to new client projects (Refactoring History). And Eclipse did it several years ago (3.2?), so in fact it's NetBeans that is playing catch-up (even if its version of the feature looks superior).

Too bad that JackPot seems to be abandoned, it would be more powerful and expressive, much better than either Eclipse's Refactoring History or this new scheme with structured annotations (IMHO). JackPot would put NetBeans in a clear leadership for this stuff.

Liam Knox replied on Tue, 2008/11/11 - 12:07am

Nice idea, I have toyed with such forms before i.e. @RefactoredTo etc, but I think this @Transformation annotation seems overly complex.  I think they were wrong not to allow textual information in @Deprecated, even a simple string would help

Casper Bang replied on Tue, 2008/11/11 - 6:45am

Now that's seriously cool. Would that be completely orthogonal to jackpot?

Jaroslav Tulach replied on Wed, 2008/11/12 - 4:39am

Thank you all for your nice words. We hope the project will be compeling for many API designers and also for IDE vendors. If anyone knows someone from Eclipse or Idea to join us in providing IDE support, please ping them.

 You are right that the project is sort of JackPot 2.0. We are well aware of our heritage and we are building upon the shoulders of those who created it. From user point of view we are "just" building a facade over JackPot - it used to have its rules files, now we will provide annotations. As such the ideas remain the same, yet we are now able to implement them with a higher level concept. This allows us to tight the annotations closer to the code, and deliver the whole system in a way more approachable by Java developers.

 Yes, the IDEs can generate these annotations automatically when doing refactorings. And yes, we know Eclipse has this functionality for ages. But this is not what we are searching for, we want to support complex refactorings that are necessary when designing APIs - such transformations go far beyond rename, move, push, pop, etc. - they are quite different. We want to allow our transformation language to express them and we want to see this done in an IDE neutral way.

 Thanks for your interest and tell me: When you will annotate your first API method with @Tranformation annotation?



James Ervin replied on Sun, 2008/11/23 - 9:16pm

This is interesting, just wish there was a more concise way to do this and a good way to develop tools for the end developer.  What I mean, is that this annotation is one that can quickly go out of date, and is there a way to make sure that the obvious foolish mistakes not be made?

 I think Eclipse API tooling takes a better tack on this or rather can compliment this, even though it is not currently directly concerned with deprecation.  I mean the Eclipse API tooling is well suited to let you know that you are breaking external API.  Perhaps this delta could be used to generate the contents of that annotation somehow or at least a marker to let the developer know that this needs updating.

 I love language featues, but if they are not backed by tooling that can be developed, they are not very useful. 

Zdenek Tronicek replied on Wed, 2010/10/20 - 3:06pm

RefactoringNG enables you to describe a refactoring as transformation of one AST to another AST. See

Commonwealth Towers replied on Mon, 2014/04/07 - 9:17pm

This could mean further price declines this year, given the bumper supply of new homes expected to hit the market and potential interest rate hike. detached

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.