Managing Taekwondo Tournaments on the NetBeans Platform
By Geertjan-Oracle on May 27, 2010
Below, I want to share my initial thoughts relating to porting the application. Maybe it will give others pointers when doing the same with their own project. I.e., a logical first step is to just browse through the sources of the original app and get to know it, assuming (as in this case) you didn't create it yourself. In doing so, the idea is to map the sources conceptually to the NetBeans Platform, which is where you want to port it. If you're new to this process then, in doing so, you need to get hold of the Essential NetBeans Platform RefCard, which gives you a high level overview of what the NetBeans Platform provides.
OK, so let's look at the sources, at least, in a screenshot:
Let's run the application. We see an empty screen, together with menu items and toolbar buttons:
Take note of the menu items that are displayed. These menu items need to always be enabled. Except... for the "Save" menu items, which don't make sense to be enabled at this stage. Looking at the next set of menu items, you can see that there's conceptually something like contextually enabled menu items available within the application:
Here I've opened a Taekwondo sample file (custom file type, created via binary serialization), which populates the Tournament window, which is a JPanel opening into the main application window:
And here I've clicked "Players" in the "Edit" window, which shows me the JPanel for players, opened into the main window, while the existing JPanel is closed:
When I choose "Matches", I see another JPanel, which includes widgets from the Visual Library:
Making an initial port to the NetBeans Platform, just as a quick prototype to see the possibilities and limitations, I end up with this application:
Here the external libraries are wrapped into modules ("Batik", "SVG", "Calendar", and "RXTXComm"). You could put each JAR into a separate module or you could put all JARs into the same module. Read What is a library wrapper module and how do I use it? in the FAQ for details. It makes most sense to put the JARs that relate to each other (e.g., all the Batik JARs) into the same module. Now you can version it and you can also make clear dependencies between the different parts of your application.
How do you decide when to create a new module and how do you decide which classes from your old application go into which modules in your new application? Module boundaries are a good starting point, as How to Split an Application into Modules? explains, though there are many variations depending on your needs, as described in that article. For the moment, I have two separate modules for the model classes together with the utils package, though all of these should probably end up in the same module, makes sense since the classes have dependencies on each other, in some cases a util class will depend on a model class, while the model class will depend on the util class. Splitting these into separate modules will cause circular dependencies, which the NetBeans Platform prevents. Therefore, better to put the model classes and the util classes into the same module, especially since the util classes are so closely tied to the model classes.
I then have a separate "TaekwondoView" module where I have simply copied all the rest of the code. That's OK for a first prototype. I had to uncomment all the action annotations from JSR-296. I created a TopComponent for each JPanel. (That means the end user will be able to edit tournaments, players, and matches all at the same time, rather than [as currently is the case] only have one JPanel available at a time, containing either tournaments, or matches, or players.) None of the actions worked anymore, they'll need to be ported to ActionsFactory methods, such as alwaysEnabled and context. The benefit of the NetBeans Platform Action system over JSR-296 is that all the actions will be centrally registered. I.e., you will know where ALL your actions are found in ALL the modules in your application, unlike the scattered actions I found within the application.
The actions were now all disabled, since they all need to be ported to the NetBeans Platform's declarative system (which will bring many benefits in addition to the central registration benefit), but it's already possible to run the application and see the panels open in the TopComponents, such as this one here:
However, the biggest limitation in the current design of the application is that you can only work with one tournament at a time. When you open or save a tournament, a ".torx" file is created using binary serialization. The next step will be to create a project type for Tournaments, which will be based on a new XML format. The XML file will be parsed when it is opened, creating nodes within a project structure. When a tournament is saved, the current data will be saved to the XML format.
So, the first step, the crucial step in porting this application, is to use the Project API, which is part of NetBeans IDE's APIs, as described in Project Type Module Tutorial. Each Tournament project will be defined by the existence of a folder named "tournamentProject", which will contain a file named "tournament.xml". (That structure is comparable to "nbproject/project.xml", which is used by NetBeans IDE.)
For another example, look at the Neuroph NetBeans Platform Porting Project. The very first step they worked on was to create project support for their application. Based on that project, everything else is possible:
Therefore the first step in this case is to create project support for creating new Tournaments.
What I find quite interesting is that the vision for this application is that it should be a generic framework for all kinds of sport activity registrations, not just taekwondo! :-)