New Gmaps4JSF plug-in architecture

Chances are that if you have ever needed to add some kind of geolocation to a "enterprise" application you have met GMaps4JSF. For those who haven't the name says it all really but, nonetheless, I will translate for the lazy, Google Maps for JSF, that is. There are other alternatives, and good ones, like say Richfaces but AFAIK this is the only one that works wirh JSF 1.1, 1.2 and 2.0, with or without AJAX, with or without Facelets and so on. Basically it works everywhere.

The library is pretty complete as it already supports the map component and several children like markers, information windows, event listeners, street views et al. But it didn't span beyond what Google offers. Till now I should say. The thing is a client asked (some time ago) to provide some map functionality that unfortunately wasn't covered by Gmaps4JSF. I tried a pure Javascript approach first but, obviously, the results were not elegant in an otherwise pure server side application. Then I tried patching the library. In the end I did the job but this solution had also many drawbacks, the main one being that future releases would be incompatible with the changes and would leave the client stuck with an old version and without access to bug fixes. This was unacceptable. So I asked Hazem Saleh, the author, about a third way, creating a plugin system that could allow me and others to create new functionality without touching the core. We quickly agreed of course :-)

Hands on with the task I devised a possible alternative. As Gmaps4JSF is Maven based it needed to be a new module. That was pretty clear from the start. I then tought about diving it even further and force the creation of new subprojects inside this module. Two problems remained, the first being the distribution (because I didn't want to require a new JAR download for each new plugin) and the second the integration with the core (because it should be seamless for the user).

The former issue was solved by using the Shade plugin. I tried the Assembly plugin before but felt short soon. Both Maven plugins allow the developer to group project artifacts and apply some rules in the process. The sahed plugin fitted better because it allow us to combine all JARs in a single one AND merge XML and text files to obtain a unique tag library as the result.

The later was solved by designing a very simple (we want other people to contribute!) plugin architecture in the core. Just one interface (three methods) is enough to determine how a plugin interacts with the rest of the environment. So to build a new plugin you just need to follow these steps:

• Get the idea
  My first two plugins were ported from the gmaps-utility-library project (drag zoom and tabbed max content). There are many other.
• Create a Maven module
  Inside the Gmaps4JSF use the maven archetype to create a new module under the plugins folder. Add it to the parent POM if so you desire.
• Declare the attributes of your component
  Just copy&paste one the available components and edit the attributes you need (for example, latitude and longitude).
• Implement the Plugin interface
  You have examples available so it should be pretty straightforward. You have access to the parent component (where your component is nested) and the map (both in JSF and Javascript).
• Register the plugin
  Just add one line (for each plugin) with the name of the implementation class to a plugins.txt file in your META-INF directory.
• Create an example
  Nothing sells an idea better. It's just a simple JSP page.

And that's all really. If you decide to contribute an addition to the project drop a line in the mailing list. There are many interesting extensions to the map API so now you have the opportunity to colaborate without the fear of having to understand the entrails of JSF or the code of Gmaps4JSF. And for the rest, enjoy the current work!