Workspace optimization

The simplest and most efficient setup is to have Maven generate an Eclipse project file for your projects. This allows Eclipse to compile your sources in the background, which it is going to do anyway, while adhering to the Maven 2 directory structure. The first step is to add a Maven repository variable to your workspace with a command like this one:

mvn -Declipse.workspace=/home/me/workspace eclipse:add-maven-repo

Then download available library sources and create the project metadata (dependencies, source and target directories):

mvn eclipse:eclipse -DdownloadSources=true

Import the project to your Eclipse workspace. Try a running a clean build of your project and confirm that your HTML templates and any other resources are copied into the correct packages under target/classes. If not, your Eclipse configuration may be filtering them out. (Search for “building” in Preferences, expand Output, and inspect Filtered Resources.)

Whenever you upgrade to a new version of Databinder or add other dependencies to your pom.xml, you’ll need to rebuild the Eclipse project:

mvn -DdownloadSources=true eclipse:clean eclipse:eclipse

Eclipse plugins

As mentioned above no plugins are required to launch a Databinder application, but you may find it helpful to have a decent HTML and JavaScript editor. The Aptana Eclipse plug-in is great for editing Wicket’s plain HTML templates (with a preview pane), JavaScript sources, and style sheets. Its HTML syntax validation red-flags some Wicket tags, which you can filter out with a string of .*wicket:.*

To integrate with Maven 2, install the Mevenide2 plugin via the Update Center, as described part-way down this page. This allows you to open any project with a pom.xml directly. NetBeans will use Maven to build the project, which is more capable than the internal build Eclipse would perform with a project generated by eclipse:eclipse, but also much slower.

So long as the project is configured for JAR packaging, its properties page will have “Run” category where the main class and working directory (use the project directory) can be set to run Databinder’s embedded Jetty server. Note that running the project in that manner does not require a bundled server; it works fine on the NetBeans “Java SE” edition. (The “Web & Java EE” edition adds 70 MB to the download.)

Although the Databinder basic application template comes configured for HSQLDB, it’s a good idea to switch to an external database before you get too comfortable. MySQL is, of course, available on just about every hosting service and using it for development means you easy shuttle data in either direction, as needed, with mysqldump. (But of course you can use any Hibernate-compatible database with Databinder.)

As mentioned in the prerequisites, Mac users can get MySQL through MacPorts (sudo port install mysql5). Most Linux distributions will also have a custom packaged version. Otherwise, there’s always the regular downloads.

You may want to adjust MySQL to default to InnoDB and UTF-8, for convenience. (It’s kind of annoying to realize later that all your tables defaulted to early ’90s technology.) This is done in the my.cnf file, which may be in /etc, /etc/mysql, MacPorts: /opt/local/etc/mysql5, or in some path with capital letters and spaces in it for Windows. If this file exists, find its [mysqld] section. If it doesn’t exist, you can create it with only the [mysqld] section.

[mysqld]
default-character-set=utf8
default-table-type=InnoDB

You will need to restart the MySQL server, and it’s best to drop databases and start over completely. Following that you should be able to rollback transactions and insert Chinese characters without issue.

Warning: Some applications (often in PHP) assume the standard MySQL defaults are in place and will fail otherwise. As always, be careful when making changes to an active Web server.

You wouldn’t know it from the tutorial up to this point, but Maven isn’t the only dependency manager on the block. Buildr is a build system that works with Maven repositories and can build Maven artifacts, but uses a Ruby buildfile rather a pom.xml. Why? Because you can program builds that way.

Buildr requires working Ruby and RubyGems installations (which can come in handy, anyway). And it might require some serious head-scratching if you’ve never written any Ruby. In short, it’s only for those who are up for a little adventure.

To help get you on your way, the Databinder example and template applications all come with a buildfile in addition to a pom.xml. You can build and run them just as with Maven, and also: see that dep_preview directory with the files that make HTML previewing decent? Buildr pulls those right from the Databinder JAR. See tasks/databinder.rake for that and other utility functions.

With your IDE tweaked-out and ready to go, it’s time to stop configuring and start programming. Read through the examples if you haven’t already, and try running them locally. They’re all set for a different MySQL database in hibernate.properties, but you can change that to HSQLDB (as in the template app) if MySQL is not cooperating.

When you add annotated classes to your Hibernate configuration, tables to hold them and their mapped properties will be automatically created as your application is starting up. Tables and columns will never be deleted from an external database, so drop them or the entire database yourself whenever you want a fresh start.

As soon as your own application goes outside the conceptual bounds of the examples, you’ll probably run right into some transient object and property not found exceptions. Take a pit stop at Models Inc. and call us in the morning.

Now go pop a wheelie. If you skin your knees, we’ll help you out on the forum.