Book of Vaadin - Vaadin 7 Draft Edition

I just sent the Book of Vaadin, Vaadin 7 Draft Edition, to print. I've been really busy with it for the last month, as there is so much to do. Some years ago, when we went from IT Mill Toolkit 4 to 5, it took over six months to rewrite it. Now the book is many times bigger and the changes in Vaadin 7 are really radical.

The edition is really a draft, and it says so right in the title and in many places inside the book. Many of the changes in Vaadin 7 require going through the book almost word by word, so I hope to get it done before the end of the year.

Also, the last batch of Vaadin 7 enhancements is yet to be released in the first beta, which should be out at the end of August.

The printed book will be available at JavaOne, and at some other locations. We try not to print this draft in huge numbers, just for the most important conferences in fall of 2012.

Big Changes in Vaadin 7

The first big thing in Vaadin 7 is the renewal of the basic application API. You no longer extend Application to write an application, but a Root (name is subject to change). Root is much what Window used to be, and the Window now means only a sub-window. There's also a separate Page object associated with a Root.

Another big topic is the client-side API, which has been essentially rewritten to use connectors that communicate between a client-side widget and the server-side component. The framework handles state object serialization transparently, and there is also an RPC mechanism. Hence, the client-side development chapter has been rewritten from scratch and it still needs a lot of work.

For most developers, also forms and data conversions are very important. There is no longer a Form component, but a FieldGroup that helps in binding fields and data together. I have written probably a hundred examples that use the old Form, so there's quite a lot work in converting them all to the new model.

And there are dozens of other significant changes.

Vaadin += GWT

Then perhaps the biggest thing in Vaadin 7 is that it now includes GWT. Just putting the GWT classes inside the Vaadin JAR sounds does not itself sound significant, the significance comes from the consequence that as we provide support for Vaadin, which now includes GWT, we also provide support for GWT. Vaadin now also effectively supports two development models: one for the server-side as before, but also for pure client-side applications.

Pure client-side Vaadin applications are of course more restricted, but they have their uses. Not all applications need data from a server, but just work on data input by the user. Also, pure client-side application can work off-line, unlike server-side Vaadin applications (unless you install the server on the client machine). For example, the Vornitologist demo for TouchKit has an off-line mode that displays a pure client-side version of the application when the network is not reachable. It uses HTML5 local storage to store the application itself, as well as the data, until the network is reached again and it can send the data back to the server. Then, the application can revert back to the full-featured server-side application. To try it out, run the demo on either an Android or iOS device.

References

Some links:

• Book of Vaadin for Vaadin 7 (HTML, PDF)
• Book Examples for Vaadin 7
• Vaadin 7 Mini Tutorials written by the DEV team
• Download page with many Vaadin 7 links

Notice again, that the Book and the book examples are really unfinished drafts at this point, and will be in better shape at the end of the year when Vaadin 7 is planned to be released.

New revision of Book of Vaadin is out

Work stuff. We have been getting a new revision of the Book of Vaadin out about every six months and the latest came from print today. This time we didn't increment the edition number, so it is the 1st revision of the 4th Edition. Essentially, one major reason was that we ran out of colors in the Vaadin color palette so the new revision looks just as yellow-orange as the original 4th Edition.

Regardless of the similar appearance, the revision packs almost 100 pages more content. The biggest change is the reorganization into two parts: the core framework and the addons. Some new add-on documentation is included in the core part: Vaadin Control Panel for Liferay, Vaadin IPC, and Vaadin WSRP. The SQLContainer add-on is now part of the core framework.

Of the add-on documentation, the JPAContainer chapter was entirely rewritten couple of months ago and the Calendar chapter was revised more recently.

Unfortunately, there are some outdated parts that went to print. Most notably, there is a really outdated material in the Vaadin embedding section, related to version 5.2. I hope there isn't much Toolkit 4 stuff left, just cleaned some references out at the last minute.

This all applies only to the print edition, which you can pick up for free at some conferences. The web edition is always the latest and it gets all additions on the same day I edit it.

Vaadin 7 is in the works. We hope to get a preview edition of the Vaadin 7 book out in the summer, in July or so. Perhaps it could be red, if we begin the color cycle in the same order we did with Vaadin 6. The color is always a big decision.

JPA and Vaadin JPAContainer

I've been finalizing the completely rewritten chapter about Vaadin JPAContainer this week. I still need to check that everything really important is included.

I don't have almost any previous experience with JPA, which is kind of good thing when you write documentation about something. That way, you personally know all the questions a beginner would have.

JPA and ORM in general seem pretty important technologies. Whatever your application is, you most probably need some data storage. Using ordinary files is possible, but not near as handy as proper databases. However, stuffing complex class structures through the square holes of database tables was a hell before the ORM technologies emerged. XML databases and NoSQL were much nicer for structured storage.

Some years ago I did some experiments with related technologies, such as JAXB and Hibernate, but using them was a bit too much effort at that time. Using Hibernate with Vaadin really required a Container implementation, but there wasn't one at that time. Well, JPA is quite close to Hibernate, and Hibernate is currently one of the JPA implementations.

Vaadin JPAContainer makes things really easy.

// Create a persistent person container
JPAContainer<Person> persons =
    JPAContainerFactory.make(Person.class, "book-examples");

// You can add entities to the container as well
persons.addEntity(new Person("Marie-Louise Meilleur", 117));

// Bind it to a component
Table personTable = new Table("The Persistent People", persons);
personTable.setVisibleColumns(new String[]{"id","name","age"});
layout.addComponent(personTable);

So, just one command to get a container bound to data in a database table. JPAContainer is, however, just for binding user interface components directly to data. You can use it to add or edit the data, but using pure JPA is much nicer, easier, and more flexible for that.

EntityManager em = JPAContainerFactory.
    createEntityManagerForPersistenceUnit("book-examples");
em.getTransaction().begin();
em.createQuery("DELETE FROM Person p").executeUpdate();
em.persist(new Person("Jeanne Calment", 122));
em.persist(new Person("Sarah Knauss", 119));
em.persist(new Person("Lucy Hannah", 117));
em.getTransaction().commit();

Well ok, here we got the entity manager from the JPAContainerFactory, which makes that a bit easier than normally.

JPAContainer is a commercial product. That shouldn't be a problem if you're coding for a company that can pay the license. For free software, you can use the AGPL license. I've always felt that this sort of dual-licensing scheme is most difficult for "potential startups" where you experiment with a business idea, but do not yet have a company to back it up financially. You do not normally have the money to invest in licenses at that point, and a company might not want to invest much in such experiments either.

There are of course alternatives for JPAContainer. Using pure JPA is quite OK approach as well, combined with BeanItemContainer in Vaadin. There's also SQLContainer. It is also something I don't know about, as I didn't write the chapter myself. I would need to review and reorganize it in next weeks though, and possibly rewrite at some point.

Well, I did make a couple of mistakes while writing the JPAContainer chapter. The first one was trying to just update a really complex design documentation written by someone else, in a topic I knew nothing about. Writing is always a learning experience and it's not sensible to try to write about something very complex that you don't have a clue about. Sometimes, it's best to start from scratch. Unfortunately, I didn't do that when I started, but just over a week before the release.

Another issue is learning by doing. I usually start writing documentation by experimenting how it works, making some example code. This time, as I was in a hurry, I tried to skip that phase. I only started it as the last effort when I was totally stuck, some 4 weeks of struggle behind and 2 work days before the release date. Just in those couple of days, all pieces fell into place and I finally understood how everything works.

Theme Development in Liferay

After installing a portal system (or web server), the first thing you want to do is create a simple web page and start customizing the theme. Unfortunately, Liferay's documentation is terribly unclear about that.

Well, its suggested normal method is to choose from a number of ready themes. Umm, NO! Nobody wants to use a theme like that. Every organization has their own colors and graphics and if not, you nevertheless want to have something that you have in your mind, not what some others have.

So, the "advanced" method is to develop a custom theme, which you can then deploy in Liferay. The Liferay plugin for Eclipse supports that. However, that method is way too heavy for me at least. I don't want to run a separate development Liferay on my machine, as I don't have enough memory in my home computer to do it fast enough. I want to work directly with the production server. I also suspect that deploying a theme takes longer than a second.

So, what I wanted to do was to just edit some CSS in the web server, save, reload, and see the result. This method of themeing does not seem to be documented anywhere, or at least it's hard to find. Anyhow, the easy way seems to be to edit the custom.css file in "classic" theme. The full path to the file is tomcat-x.x.x/webapps/ROOT/html/themes/classic/css/custom.css.

The problem with that was that just editing it did not reload it immediately, or actually ever. Even restarting the serve does not reload it. I found some suggestions for properties that would need to be set in the portal-ext.properties, but they didn't quite work in my case.

Finally, I found the solution right there in the Liferay's installation package. The file tomcat-6.0.29/webapps/ROOT/WEB-INF/classes/portal-developer.properties has the following settings for development:

theme.css.fast.load=false
theme.images.fast.load=false

javascript.fast.load=true
javascript.log.enabled=true

layout.template.cache.enabled=false

browser.launcher.url=

combo.check.timestamp=true

freemarker.engine.cache.storage=soft:1
freemarker.engine.modification.check.interval=0

openoffice.cache.enabled=false

velocity.engine.resource.manager.cache.enabled=false

com.liferay.portal.servlet.filters.cache.CacheFilter=false

com.liferay.portal.servlet.filters.themepreview.ThemePreviewFilter=trueroot

I don't actually know which of the settings are really necessary, but now it seems to work great. Just edit the file and it's reloaded immediately.

Installing Liferay on MySQL

I'm installing a new web server for the astronomical association Turun Ursa. As we support Liferay at work, using it for this purpose may have some synergy so that I don't need to learn yet-another-portal. Well, not that Liferay is the easiest to learn. Anyhow, it also makes it possible to develop some portlets if I ever need one. I think I may need to redo my planetarium application again in Java - the old C++ version for Sparc stopped working some time ago after some upgrade at the university.

Anyhow, the instructions for doing the proper installation were rather unclear as they didn't really tell much details about creating the database. They referred to a "Chapter 6", which didn't exist at all. I guess they referred to these instructions, which were more helpful. Anyhow, below is a brief summary.

The setup is done here using the database root user. Some Liferay example used that though I don't really see why. Creating a separate Liferay user might be nicer. Well, I have Liferay running as a root anyhow to get it running in port 80, so the database user probably doesn't make it significantly safer.

1. Shut down the server

   # ./tomcat-6.0.29/bin/shutdown.sh

   ...and wait for a bit.

2. Move the 7Cogs demo data generator away

   # mv tomcat-6.0.29/webapps/sevencogs-hook/ .

3. Create the database with a database command and not using the mysqladmin to be able to set the character set. It's probably important.

   # mysql -prootpassword
   mysql> create database lportal character set utf8;
   Query OK, 1 row affected (0.00 sec)

   The MySQL configuration stuff is explained in this wiki.

4. Create a portal-ext.properties file in the Liferay installation directory with content:

   #
   # MySQL
   #
   jdbc.default.driverClassName=com.mysql.jdbc.Driver
   jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
   jdbc.default.username=root
   jdbc.default.password=rootpassword

5. Start up the server

   # ./tomcat-6.0.29/bin/startup.sh

6. Follow that it starts OK

   # tail -F tomcat-6.0.29/logs/catalina.out

Well, rather trivial but took me a bit time as the documentation was a bit...hazy.

Other notes:

• When first logging in, create a new user account with your own name. Then log out and log in as user "test@liferay.com" with password "test" (this information was not really obvious in the instructions either). Go to Control Panel -> Users and give yourself the Administrator role. You need to remove or disable the "test" account at some point...