New Adventure Begins: Vaadin

I’m exploring Vaadin, a framework for server-side webapps that require no knowledge of HTML, CSS, DOM, JavaScript, or HTTP. Similar in concept to Real Studio, Web Edition, but built in pure Java. Vaadin is quite promising, as seen in this great demo of their rich collection of GUI widgets, and excellent doc in The Book of Vaadin.

Unfortunately, getting started with Vaadin is almost impossible. After strange initial behavior, and wrestling the Eclipse IDE, I gave up trying weeks ago. I was quite disappointed given how you can have a working interactive web app running in your first 5 or 10 minutes with Real Studio. However, my greatest strength as a developer kicked in: stubbornness. I tried again. And I’ve nearly won this time.

So here’s some pointers for other brave souls venturing into the world of web apps.

Tip 1: Use Eclipse

While Eclipse is my least favorite Java IDE, the Vaadin plugin is designed only for Eclipse. Be sure to get this edition, Eclipse IDE for Java EE Developers. In theory, you could use another edition of Eclipse  and add enough modules to get the equivalent of the EE edition. I tried, I failed. I already had another edition for other purposes (Swing apps). I added and added modules, but never got it to work. Reading the Vaadin forums led me to many answers asking “Did you start with the Java EE edition of Eclipse”. So I gave up, replaced my Eclipse, and found some success.

Bonus: I found I could add the WindowBuilder modules to the Java EE edition, thereby giving me the best of both, Swing and web apps.

I am using:

Eclipse Java EE IDE for Web Developers.
Version: Indigo Release
Build id: 20110615-0604
with Mac OS X 10.6.7 on an Intel MacBook Core 2 Duo, 6 gigs of memory, executing in Tomcat 7.0.21 under Apple's implementation of 64-bit Java 1.6.0_26.

Tip 2: Use the Vaadin plugin for Eclipse

While not technically necessary, the plugin is virtually a necessity. The plugin creates a properly configured Vaadin web app project with a Hello World application. The plugin provides other features as well.

Tip 3: Let Eclipse download and install the Vaadin plugin

I naïvely downloaded and installed the plugin myself. That led to problems. Among other things, Eclipse offered to upgrade the plugin later, but could not actually do so. To install the plugin the proper way, let Eclipse do it.

1. Choose Help > Install New Software. 
2. In the Work with field, paste the URL as instructed by the Vaadin site.

Tip 4: Install Tomcat before using Vaadin

Download, prepare, and configure Apache Tomcat before you start using Vaadin.

Download: Unzip the Tomcat download. You may put the Tomcat folder anywhere. I put it at the top of my home folder.

Prepare: See another post of mine explaining how to perform the crucial step of running your unzipped Tomcat through the BatChmod app if you are running on a Mac.

Configure: You must tell Eclipse how to work with your Tomcat installation. As I’ve forgotten how at this moment, I'll try to write another post on this topic.

Tip 5: Create your first project as a Vaadin project using the Wizard

In Eclipse, choose File > New > Other. In the Wizards filter field, type: Vaadin. From the list, pick "Vaadin Project". For the most part, go with the default values in the wizard. If you are doing real work, as opposed to the tutorial, change the base package to your own.

Tip 6: Build before running

The resulting project should be ready to run. Except that for some mysterious reason, the wizard's Run configuration fails to first build the project. So to run:

1. Select the name of the project in the Project Explorer. (Crucial!)
2. Choose Project > Clean Project (Crucial! Successive runs do not freshen properly unless you clean -- don't ask me why)
3. Click the Run button in toolbar.

If you are lucky, Tomcat launches, and after several moments your app appears in Eclipse's built-in web browser. Eclipse lets you specify using a real web browser instead. But when I tried Firefox, I got annoyed my Eclipse telling me to close all windows in Firefox or quit Firefox. Hopefully I can solve that problem another day.

Tip 7: Stop Session Persistence

After my first successful run with the Hello World app, I did what any eager student does. I tweaked the app, and ran again. I added a "new java.util.Date" to the app's Hello label. I ran my app again, but no date. I stopped the Tomcat server, and tried to run again. No date. I quit Eclipse and restarted and ran. No date. Arghh!

Turns out to be a feature, not a bug. Unbeknownst to me, by version 7, Tomcat had acquired the default behavior of persisting sessions automatically. So when Tomcat shuts down, any existing Session objects have their values written to disk. When that web runs again after restarting Tomcat, the sessions are reconstituted in the JVM. 

Meanwhile, the Hello World app created by the Vaadin project wizard has its gui constructed during a call to the Vaadin 'init' method. Turns out, the init method is only called when starting a new session. Since Tomcat was reconstituting the old session on every run, the init method was never being called again. So my edits to the init method never took effect. This tricky Catch-22 cost me hours and hours of frustration and confusion. 

To avoid this behavior:

1. As mentioned in Tip 6 above, always Clean rather than build your project.
2. Turn off the Tomcat feature of persisting sessions.

To disable that Tomcat feature, install a configuration file.

1. Locate the "context.xml" file found in the "conf" folder of Tomcat. In my case: /Users/basilbourque/apache-tomcat-7.0.21/conf/context.xml
2. Paste a copy of that file to the "WEB-INF" folder of your Eclipse project's "WebContent" folder. In my case: /Users/basilbourque/Documents/workspace/myproj/WebContent/WEB-INF/context.xml
3. Edit that new "context.xml" by uncommenting the line reading: <Manager pathname="" />. Note that the comment itself explains this will disable the session persistence feature.