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

10 Tips for Porting to the NetBeans Platform

  • submit to reddit

I'm aware of several groups of developers who have recently started porting Swing applications to the NetBeans Platform. In the aftermath of the JSR-296 meltdown, that trend is likely to become even more prominent.

That, in fact, may be the biggest win of the JSR-296 project—it helped developers take the next step in their projects, which they otherwise might not have done. I.e., developers abandoned the JFrame, swapping it for the JSR-296 SingleFrameApplication class. Since it was so easy to get started with JSR-296 (I refuse to call it "Swing Application Framework", simply because the name arrogantly and mistakenly implies that there is no other Swing application framework), especially with the help of the tools in NetBeans IDE, many developers did so, quickly bringing their applications to fruition.

However, it's never been more than a JSR and its development has ceased, as described in the warning you'll see when you try to create these applications in NetBeans IDE 6.9:

And so, now even more developers are in need of the NetBeans Platform, since that's the most logical next step for your Swing application, especially if you've committed yourself to a larger source base, which is what the adoption of JSR-296 implies, i.e., you didn't find the JFrame sufficient, you wanted to focus on your domain rather than its infrastructure, hence you needed lifecycle management, and an Actions system, and Tasks. So, now you still need them, and they're all available in the NetBeans Platform.

Here, based on quite some interaction with developers entering the process of porting applications to the NetBeans Platform, are my top 10 practical tips for getting you started:

  1. Follow the CRUD Tutorial. Yes, there are many tutorials you can take and screencasts you can watch. However, if there were to be one specific tutorial, which would it be? It would be the NetBeans Platform CRUD Application Tutorial. I was recently in touch with a developer who was pretty confused about many things relating to the NetBeans Platform. After following that tutorial, the kinds of questions he ended up asking were markedly different, far more in line with the idioms of the NetBeans Platform. That specific tutorial covers the most typical scenario on the NetBeans Platform and in the process you learn a LOT about the typical ways of working on the NetBeans Platform, the processes, the APIs, everything you're going to need to learn at some point anyway. So why not follow that tutorial and you'll be off to a flying start. (The completed CRUD application is available in the IDE from 6.9 onwards, both as a Maven-based application and an Ant-based application.)

  2. Print Out the NetBeans Platform Refcard. A very big problem when confronted with the NetBeans Platform is that of scope. In other words, what does the NetBeans Platform provide, exactly? Why would you use what when? Again, the screencast series helps a lot in that regard, but you should really get (for free) and print out the Essential NetBeans Platform Refcard. It really covers everything on a very global level, as well as drilling down to the finer details, giving you lots of code tips and tricks along the way.

  3. Prototype. Do a quick prototype. I.e., right after having followed the two steps above, you actually already have everything you need. It's all a lot less complicated than it might seem. Make a back up of your source code, create a new NetBeans Platform application in NetBeans IDE (or use one of the Groovy scripts provided by the IDE for the same purpose), create a new module, and then stick all your code into that single module. Next, create library wrappers for all your third party libraries. Set dependencies as required, create a TopComponent (which you know how to do, since you completed step 1) and then display some of the data in a new window in your new application. That's it, your first prototype is complete.

  4. Turn External JARs into Modules. A frequent pain point is where developers say: "Really? Do I need to turn all of my libraries into library wrapper modules? Why?" Well, the idea is that you're creating a modular application, which lets you benefit from dependency management, versioning, and information hiding. It is a great benefit to also be able to version and manage the dependencies of your 3rd party libraries. You can even put multiple JARs into the same module (via Ctrl-Click and Shift-Click in the "Library Wrapper Module wizard"). However, you need to think about the wisdom of putting multiple JARs into the same module, as (remember!) you're creating a modular application, so only those things that NEED to be in the same module should be in the same module.

  5. Think on Module Boundaries. When to create a new NetBeans module (or OSGi bundle)? It is very important that you read the article How to Split an Application into Modules?

  6. Register Action Classes. Since the 6.7 release of the NetBeans Platform, you typically do not need to subclass the NetBeans Platfor's Action classes anymore, as explained in Which NetBeans Platform Action Class Should I Use? Why is that a good thing? Because now you can simply copy the ActionListeners and AbstractActions from your original application and paste them into your NetBeans modules. Once you've done so, all you need to do is register them correctly and then you're done. That means that porting your Action classes to display them in menus, toolbars, and have them invoked from keyboard shortcuts is a question of registration, rather than recoding the classes.

  7. Love the Layer. The layer is your best friend. A "layer" is an XML file, of which each module can have at most one. Each layer is added to the virtual filesystem of the application at start up. You can register anything you like in the layer and then, from your Java code, you can read that layer. That sounds very abstract, but look at "Pluggable JXTaskPane" for a very simply and typical example. That's also the magic to turning your application... into a platform! Create a folder in the layer (i.e., simply by typing in an XML file) named "Products" and then each module providing a new product can register a folder below "Products". Then in your code, you can iterate through the Products folder, find all the products, and then display them in a window in the application. Service providers can be registered in the layer too, as explained in How Do NetBeans Extension Points Work?

  8. Keep the JPanels. You have JPanels in your original application? Wonderful. You can use them without making any changes whatsoever. Create a new TopComponent class (either via the wizard in NetBeans IDE or by simply subclassing "TopComponent"), then call "add(myJPanel)", and then you're done. No more work needed than that. You can do the same thing with the Options window or a wizard. I.e., you might find that a JPanel can be used to configure something (in the Options window or in a wizard), as well as as an edit panel in a window. So you can reuse that same JPanel in multiple different places, simply by calling "add(myJPanel") in whichever NetBeans Platform container you're working on.

  9. Participate in the Community. You'll definitely get more out of things by participating, which mainly occurs in the mailing list. All sorts of questions are asked and answered there and, as you learn more, you should make use of the opportunity of sharing your knowledge with others. You can really have an impact on some very cool applications being developed all over the world!

  10. Porting is a Process. Remember always that porting is a process. Typically, it takes place over many releases of your product, so plan accordingly, since there should be no regressions for the end user. For example, in the first release after you start porting, you might simply port the JPanels to TopComponents in your new NetBeans Platform application. In the next release, you might want to wrap your business objects into Node classes, so that they can be displayed in explorer views, including the Properties window. Etc. Take it slow and pace yourself. If you have a few weeks or months to work on the porting process, depending on the size of the source base, that should be OK. However, if you have less time, consider working in stages, choosing the features you want to use for each release. You only need to use as much as you need, there's no rule (except for the runtime container, which is mandatory) saying how much of the NetBeans Platform should be part of your application.

OK, that's the end of my list! What do you, reading this article, think? Do you have other tips?

Published at DZone with permission of its author, Geertjan Wielenga.


Illya Yalovyy replied on Sun, 2010/06/06 - 2:11pm

Swing Application Framework is not dead. You can find several forks around. One of them is . The most important benefits of BSAF are:

  • You can learn in in a half of an hour
  • It has stable API
  • It does not limit your development approaches
  • It is extremely easy to switch to another application framework or use BSAF in existed application.

Wai Ho replied on Sun, 2010/06/06 - 2:43pm in response to: Illya Yalovyy

  • It does not have a window system.
  • It does not have a module system.
  • It is completely unsuitable for all of these applications.

Geertjan Wielenga replied on Sun, 2010/06/06 - 2:51pm in response to: Illya Yalovyy

I can also learn to beat two sticks together in half an hour. But just because I can beat two sticks together, doesn't mean I can create interesting music... just like my being able to learn BSAF in half an hour doesn't mean I can create the kinds of applications that the end user actually needs, i.e., flexible, modular, pluggable, applications. To the end user, the fact that you can learn something in half an hour is meaningless, unless the features provided are actually powerful. Part of "powerful" in the application desktop domain is "pluggable", at least in the area of large scalable distributed applications, as opposed to applications that are toys/prototypes/etc.

Pavan Kumar Sri... replied on Sun, 2010/06/06 - 11:41pm

I think we need to acknowledge the fact that Eclipse is more widely used as an IDE when compared to Netbeans for everyday Java programming... I hope this changes one day to Netbeans...but this is the fact. A lot of Netbeans tutorials makes use of the Netbeans IDE & the wizard to get things done. If these tutorials could be rewritten,without the wizard ,and made IDE agnostic maybe for JDeveloper/Eclipse/IDea it would definitely make a huge difference the adoption of the platform , as developers/organizations can still use their favorite IDE ..but for Netbeans Platform Development. Developers can starting building/porting small parts of their large Swing application to the platform their favorite IDE before eventually moving to Netbeans. I think this was the one of the reasons behind the initial popularity of Eclipse Plugin Development. Regards, Pavan

Tom Wheeler replied on Mon, 2010/06/07 - 3:12pm

My tip is "see how much of your own code you can get rid of" after you've ported your own application to the NetBeans Platform.  Every homegrown Java project usually has a bunch of utility methods for loading images, showing error or status messages to the user or making I/O more convenient.  Since NetBeans Platform already has methods for doing these things -- and their versions are generally better written  -- I find a great deal of the original code is redundant when porting an application.

Tonny Kohar replied on Mon, 2010/06/07 - 11:54pm

I like the tip #10 and thats what I do when I was porting my application to Netbeans Platform. One of the good things regarding NB platform is that when you port you can very easily on the first time eg: just wrap your JPanel to TopComponent and you are done (and you got all the benefit that NB platform offer eg: integrated runtime container, menu/action management, plugin manager, etc)

Once you are comfortable with NB platform you can start exploring other NB platform API to replace your own API eg: utility method for loading images, log, etc

And finally when you are ready, you can start utilize the whole Nb Platform API eg: nodes, lookup, etc and you will have fully integrated platform application.

Fabrizio Giudici replied on Wed, 2010/06/09 - 5:06am

Most of the good things have been already said. But I can add one: think incrementally. Thanks to heavens, the NetBeans Platform is Swing based as your existing application. This means that you shouldn't learn all of the tremendous bag of Good Things that the platform has, but you can start from a few things, integrate them into your application, and then incrementally replace your code with the proper NetBeans APIs. At the same time, slowly but steadily refactor your stuff splitting it into properly designed modules. If you are new to module design, the Platform will teach you a lot of things.

Edmond Chouaffe replied on Wed, 2011/08/03 - 7:41am

Hi guys.

This is my first post.

I want to port my application to the netbeans platform, but I now encouter some problem:

My application has  login feature i.e. the user must first login before the real application opens.

I use two JFrames for that. When the login is successful, the first window disappears and the second one appears.

I can't figure out how to reproduce this with the netbeans platform.

My idea is to write the login window as normal JFrame ( to benefit from the incofy-able property) and then upon login, to launch the real  application which should be a TopComponent subclass as generated by default by the platform.


Do you have any idea how I can handle this?





Vladimir Sitnikov replied on Mon, 2011/10/17 - 10:02pm in response to: Edmond Chouaffe

Edmond, I have encountered the same problem! Could you share your solution if you managed to do that?

Baruch Atta replied on Thu, 2012/03/29 - 2:48pm

"...Porting is a Process. Remember always that porting is a process. Typically, it takes place over many releases of your product, so plan accordingly..."

 No! Porting is your process, not ours.  You ! should have taken more time to get this right.  You ! have done it so wrong.    Your porting process sucks.  It is exceedingly complex and totally unnecessary.   

 You should have done two things differently.

1.  You should have given warning that you intended to obsolete Swing.  I thing that two years warning would have been good.

2.  You should have continued to support Swing while urging users to adopt your new platform.  Believe it or not, many would do so willingly.  

3.  And there should be an automatic import of Swing forms into the new format.  

This issue is a showstopper.  We can not continue with Netbeans until this issue is resolved.

 "We find the decision to suddenly rip out support for the SAF from NetBeans to be outrageous, and our confidence in NetBeans for the future has been shattered.  Recoding our projects to use a different framework is not a practical option for us in the short term"

Cata Nic replied on Fri, 2013/09/06 - 3:10am

These tips helps my team to improve its effectiveness. We are able to work faster and with more success.

Comment viewing options

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