Saturday, May 5, 2012

Creating a NetBeans 7.1 Custom Hint

I have talked about some of my favorite NetBeans hints in the posts Seven NetBeans Hints for Modernizing Java Code and Seven Indispensable NetBeans Java Hints. The fourteen hints covered in those two posts are a small fraction of the total number of hints that NetBeans supports "out of the box." However, even greater flexibility is available to the NetBeans user because NetBeans 7.1 makes it possible to write custom hints. I look at a simple example of this in this post.

Geertjan Wielenga's post Custom Declarative Hints in NetBeans IDE 7.1 begins with coverage of NetBeans's "Inspect and Transform" (AKA "Inspect and Refactor") dialog, which is available from the "Refactor" menu (which in turn is available via the dropdown "Refactor" menu along the menu bar or via right-click in the NetBeans editor). The following screen snapshot shows how this looks.

The "Inspect" field of the "Inspect and Transform" dialog allows the NetBeans user to tailor which project or file should be inspected. The "Use" portion of the "Inspect and Transform" dialog allows that NetBeans user to specify which hints to inspect for. In this case, I am inspecting using custom hints and I can see that by clicking on the "Manage" button and selecting the "Custom" checkbox. Note that if "Custom" is not an option when you first bring this up, you probably need to click the "New" button in the bottom left corner.

When I click on "Manage" and check the "Custom" box, it expands and I can see the newly created "Inspection" hint. If I click on this name, I can rename it and do so in this case. The renamed inspection ("CurrentDateDoesNotNeedSystemCurrentMillis") is shown in the next screen snapshot.

To create the hint and provide the description seen in the box, I can click on the "Edit Script" button. Doing so leads to the small editor window shown in the next screen snapshot.

If more space is desired for editing the custom inspection/hint, the "Open in Editor" button will lead to the text being opened in the NetBeans text editor in which normal Java code and XML code is edited.

With the custom inspection/hint in place, it's time to try it out on some Java code. The following code listing uses an extraneous call to System.currentTimeMillis() and passes its result to the java.util.Date single long argument constructor. This is unnecessary because Date's no-arguments constructor will automatically instantiate an instance of Date based on the current time (time now).

RedundantSystemCurrentTimeMillis.java
package dustin.examples;

import static java.lang.System.out;
import java.util.Date;

/**
 * Simple class to demonstrate NetBeans custom hint.
 * 
 * @author Dustin
 */
public class RedundantSystemCurrentTimeMillis
{
   public static void main(final String[] arguments)
   {
      final Date date = new Date(System.currentTimeMillis());
      out.println(date);
   }
}

The above code works properly, but could be more concise. When I tell NetBeans to associate my new inspection with this project in the "Inspect and Transform" dialog, NetBeans is able to flag this for me and recommend the fix. The next three screen snapshots demonstrate that NetBeans will flag the warning with the yellow light bulb icon and yellow underlining, will recommend the fix when I click on the light bulb, and implements the suggested fix when I select it.

As the above has shown, a simple custom hint allows NetBeans to identify, flag, and fix at my request the unnecessary uses of System.curentTimeMillis(). I've written before that NetBeans's hints are so handy because they do in fact do three things for the Java developer: automatically flag areas for code improvement for the developer, often automatically fix the issue if so desired, and communicate better ways of writing Java. For the last benefit in this case, the existence of this custom hint helps convey to other Java developers a little more knowledge about the Date class and a better way to instantiate it when current date/time is desired.

The most difficult aspect of using NetBeans's custom hints is finding documentation on how to use them. The best sources currently available appear to be the NetBeans 7.1 Release Notes, several Wielenga posts (Custom Declarative Hints in NetBeans IDE 7.1, Oh No Vector!, Oh No @Override! / Oh No Utilities.loadImage!), and Jan Lahoda's jackpot30 Rules Language (covers the rules language syntax used by the custom inspections/hints and shown in the simple example above). The Refactoring with Inspect and Transform in the NetBeans IDE Java Editor tutorial also includes a section on managing custom hints. Hopefully, the addressing of Bug 210023 will help out with this situation.

My example custom NetBeans hint works specifically with the Date class. An interesting and somewhat related StackOverflow thread asks if a NetBeans custom hint could be created to recommend use of Joda Time instead of Date or Calendar. A response on that thread refers to the NetBeans Java Hint Module Tutorial. Looking over that tutorial reminds me that the approach outlined in this post and available in NetBeans 7.1 is certainly improved and easier to use.

Incidentally, a hint like that asked for in the referenced StackOverflow thread is easy to write in NetBeans 7.1. There is no transform in this example because a change of the Date class to a Joda Time class would likely require more changes in the code than the simple transform could handle. This hint therefore becomes one that simply recommends changing to Joda Time. The next screen snapshots show the simple hint and how they appear in the NetBeans editor.

Each release of NetBeans seems to add more useful hints to the already large number of helpful hints that NetBeans supports. However, it is impossible for the NetBeans developers to add every hint that every team or project might want. Furthermore, it is not desirable to have every possible hint that every community member might come up with added to the IDE. For this reason, the ability to specify custom hints in NetBeans and the ability to apply those hints selectively to projects and files are both highly desirable capabilities.

No comments: