Fast Introduction

Special thanks to all turbine developers.

Readers guide: please, try to read the whole story first without linking to external sites

So you want to make a good web app. And you need a framework to speed up your project and to avoid building from scratch.There are plenty of open source java web application framework available, see Wafer.

In this tutorial, I mainly use the term in P of EAA Catalog to simplify my life and trying documenting with pattern. Turbine is a MVC framework It use Template View based on Velocity templating engine instead of JSP (YMTD). For the default O/R Mapping layer it use Torque also powered by Velocity.

I am not an expert of MVC but here is my view for the tutorial example

Getting started

download the latest tdk
make sure you already installed:

Java
DB Server this guide use MySQL, others are welcome
Build tool Ant
IDE Eclipse 2.1 (recommended)

check the setting of JAVA_HOME, ANT_HOME, PATH :
(optional) if you want the source code of this example

Making a new project

after you extract tdk, we build a new project by modifying the build.properties file into

tdk.home = e:/tdk-2.2
tdk.turbineVersion = 2
tdk.project = belajar
target.package = org.jlinux.belajar
target.directory = org/jlinux/belajar

we will use the example with the schema like this one, taken shamelessly from martin fowler site (my favourite writers)

but we only try to cover the CRUD of Artist

change directory to tdk directory e.g: e:\tdk-2.2 and at command prompt/console type: ant
under directory webapps we have a complete directory structure of our new belajar web app

Setting up a new project

edit another build.properties file in pos\WEB-INF\build directory e.g: e:\tdk-2.2\webapps\belajar\WEB-INF\build

add line tdk.home =e:/tdk-2.2
edit database setting:
database.name = learn
database = mysql
createDatabaseUrl = jdbc:mysql://localhost:3306/learn
buildDatabaseUrl = jdbc:mysql://localhost:3306/learn
databaseUrl = jdbc:mysql://localhost:3306/learn
databaseDriver = org.gjt.mm.mysql.Driver
databaseUser = igi
databasePassword = igi
databaseHost = localhost

of course we must make sure that we can connect with this user first (user has the privilege).

at directory e:\tdk-2.2\webapps\learn\WEB-INF\build run ant -projecthelp and then ant init
it will looking for turbine-schema.xml and learn-schema.xml in conf and torque will generate classes for everything on them.

run the startup.bat from tdk-2.2\bin and open your browser to http://localhost:8080/learn/servlet/learn/
login with user turbine and password turbine

Making database

if you check your database, it should look like what we have in turbine-schema.xml and learn-schema.xml because Torque use Metadata Mapping
now let us make class Album and Artist by editing learn-schema.xml
make sure we have element database has name attribute with value learn, then add this line

now type again ant -projecthelp to see what we can do

type ant project-om schema-sql

you still have choice to run ant init but that only if you want to destroy your previous work

you can see the result in directory src\java and src\sql

in the file learn-schema.sql we have:

# -----------------------------------------------------------------------
# artist
# -----------------------------------------------------------------------
drop table if exists artist;

CREATE TABLE artist
(
id INTEGER NOT NULL,
name VARCHAR (255),
PRIMARY KEY(id),
UNIQUE (name)
);

# -----------------------------------------------------------------------
# album
# -----------------------------------------------------------------------
drop table if exists album;

CREATE TABLE album
(
id INTEGER NOT NULL,
artist_id INTEGER,
title VARCHAR (255),
PRIMARY KEY(id),
FOREIGN KEY (artist_id) REFERENCES artist (id)
);

this result depend on your database :)

now make your new tables copy and paste in the mysqlfront

and in file learn-schema-idtable-init.sql nothing change, so we just have to add it by our selves

For the Identity Field, torque gives you the native one (using auto increment or sequence generator) or using idbroker.

insert into ID_TABLE (id_table_id, table_name, next_id, quantity) VALUES (102, 'artist', 1000, 10);
insert into ID_TABLE (id_table_id, table_name, next_id, quantity) VALUES (103, 'album', 1000, 10);

ID_TABLE is used by idbroker to generate id, and it makes your application reallly portable across databases

in E:\tdk-2.2\webapps\learn\WEB-INF\src\java\org\jlinux\learn\om

om means object model, so this is were we put Domain Model. we will see BaseArtist and BaseArtistPeer, Artist and ArtistPeer, the first two is always generated with ant project-om

the last two are empty and we can put business logic in Artist as Entity Object and finder in ArtistPeer as Repository.

now we provide the menu to add new artist in E:\tdk-2.2\webapps\learn\templates\app\navigations\Menu.vm

we add

now login using turbine and password turbine and we have the menu, try to click on it we got

Error
java.lang.Exception: Screen template 'ArtistForm.vm' not found

now its time to make a template for the form in E:\tdk-2.2\webapps\learn\templates\app\screens

ArtistForm.vm contains:

if we use $artist.Name instead of $!artist.Name, then if the variable is empty it will print itself and no error are generated.

and if we click Insert we will have

Error
java.lang.Exception: Screen template 'ArtistList.vm' not found

so let us make ArtistList.vm first, so we can see the result.

now try to check out the result.

no error hmm thats good :), you see that designer can change the vm template without worry to much about compiling page.

now we need an action and screen class so we can insert and display the result.

I use eclipse so here we are creating new project.

you can click finish or next, after that add the activation.jar in properties of learn project, because the license can not make it included

by default eclipse automatically compile if resource modified, and if you turn it off, you can refresh and build project manually.

this is the default package/module if you have several module you can add it later, but now we use the existing one

while pointing at package action we can press Ctrl+N or right clicking to make a new class

we use SecureAction if we need one. by clicking the bulb and press Enter (or Ctrl-1 Quick Fix) we import the package

eclipse suggest to implement the interface

add this method:

this feature is very handy if you use it in TDD (Test Driven Development ) environment, check this one too

in ArtistPeer.java

Criteria is an implementation of Query Object

to make learn reloadable, edit server.xml so it contains

<Context path="/learn" docBase="learn" reloadable="true"/>

restart tomcat just for once and try to input some of your favourite artist, my list looks like:

wait a minute, they don't have album, uh doesn't bother your mind with it :),

now we just finish the CR part so let us continue for UD part, we have to modifies our template of course

we have to make screen of ArtistForm, see that I generate class ony if I need one. we follow DTSTTCPW principle.

and we modify ArtistForm.vm so it display the correct button

$data.Parameters is the same as $data.getParameters, velocity use reflection to guess the set/get method

if you try to click nothing happened, now is time for you to write the action for updating and deleting. As you see we are still using the same ArtistAction, of course you can provide one to one action and class mapping, but I prefer to put related action for one entity in one class.

now here is a magic tricks from turbine to prevent submit form duplication, add this line to your ArtistForm.vm

thats all folk for now. If we work with turbine we really work in very incremental and iterative ways :)

critique, comment, suggestion, and question about this tutorial, please send it to me