The Turbine Development Kit allows you to begin developing on/evaluating Turbine and its diverse set of components almost immediately. It includes almost everything needed to begin Turbine development. Installing it should be the first step in your evaluation of Turbine.
Much of this getting started guide has been put together using information found elsewhere on the website. It should not be seen as a replacement for reading the plethora of information available about Turbine, as new users seem to always do. It simply attempts to get a first time user up and running with the TDK quickly and with a general knowledge of how it works. As usual, please be sure that you have scoured the entire website for information before asking questions on the mailing list. Also, it is suggested that you read this entire guide before attemping to install the TDK.
Before using the TDK, you are going to need to have a Java Software Development Kit supporting Java version 1.4 or later installed on your machine. Sun's Java SDK can be downloaded from their website located here.
You must have Ant installed on your machine in order to do anything. If you do not have Ant installed, you can find out how to install Ant here. The TDK version 2.3 is known to have compatibility issues when using Ant with version less than 1.5.
In order to use the mail functions you need to download the activation.jar from here. We are not allowed to redistribute this library.
In order to do anything interesting with the TDK, you are also going to need a database that is compatable with the JDBC standard. The TDK currently comes with drivers for Hypersonic, InstantDB, MySQL, Postgres and SAPDB. Other drivers can be downloaded from the vendor's websites located here:
Simply download these drivers to any directory for now. We will make use of them later.
Not every platform/database combination has been thoroughly tested so your particular setup may require some leg work for full functionality. The following combinations are known to work and are tested with every release of the TDK:
| Platform | Database | Testers |
| Linux | MySQL | Martin Poeschl |
| WinXP | MySQL | Martin Poeschl |
If the combination is not listed here, it doesn't mean that the TDK won't work for you. It just means that no one regularly tests that combination when new TDKs are released. If you get an unsupported combination to work and you would like to test your combination please post a message to the list and we will add you to the list above.
First of all, you have to get the TDK distribution. You can fetch it from the Turbine release repository. Search for the directory with the latest version, and download the file tdk-2.3.tar.gz. In actual fact no official 2.3 build has been released, but an unofficial beta can be downloaded from here.
Unpack the TDK distribution into a directory of your choosing. On Windows, use WinZip to unpack the files and on Unix, something like:
tar -xvzf tdk-2.3.tar.gz
should to the trick. If you have met the above prerequisites, you will not need to download anything else to proceed with the installation.
Now that you have the TDK installed on your machine, you need to create a sample application in order to begin using it. This is done in the following manner:
1. Setup your local environment variables. You will need both JAVA_HOME and ANT_HOME environment values for your system. On *nix/BSD using the Bash shell, this can be done with. It may be smart to go ahead and add these to your startup system login scripts if you have not already. Your CLASSPATH environment should not affect Ant's ability to build your TDK however, if you do run into a problem, you should be able to set CLASSPATH to be empty and build the tdk sample app. I would suggest setting a third variable for ease in the rest of this sample, TDK_HOME
export ANT_HOME="/PATH/TO/ANT/" export JAVA_HOME="/PATH/TO/JDK/" export TDK_HOME="/PATH/TO/TDK/"
2. Change to the TDK_HOME directory and modify the build.properties file. You will need to add an additional property called tdk.home which should be set the same as your environment TDK_HOME. If you wish to change the name of your application, you would adjust the property tdk.project to the name you wish. You can also adjust the package and directory structure that will be created at this point if you wish. To change the default package to your own, eg. com.company.appname, change the value of target.package and to change the directory you would set target.directory These two values are usually a mirror of one another. Here follows an example of the initial build.properties located in TDK_HOME
# ------------------------------------------------------------------------- # This is where you control the initial generation of the Turbine # sample webapp. # ------------------------------------------------------------------------- tdk.home = /PATH/TO/TDK tdk.turbineVersion = 2 tdk.project = newapp target.package = org.mycompany.newapp target.directory = org/mycompany/newapp
3. Run Ant in the root directory of the TDK_HOME directory. The sample application will be generated with the default name of newapp.
ant
executed from your TDK_HOME directory, will create most of the files necessary for running your turbine app.
4. Once the initial set of files has been created, you will need to go into the directory TDK_HOME/webapps/newapp/WEB-INF/build and edit your build.properties file. This file is used to specify properties such as the type of database you are using and your DB connection info. The first adjustment you need to make is to add the tdk.home directive to the build.properties file.
# ------------------------------------------------------------------- # P R O J E C T P R O P E R T I E S # ------------------------------------------------------------------- tdk.home = /path/to/tdk
The information in build.properties is used to create the tables Turbine will be using and the classes used to access them. At this time you should also copy your JDBC drivers (renaming .zip files to .jar files) into the TDK_HOME/webapps/newapp/WEB-INF/lib directory if you are using a database for which the TDK does not provide JDBC drivers. These files will be important when creating the database tables in the next step.
To build the sample app, you will need to add the following configuration scope for torque. Since torque has been decoupled from the turbine environment, these values are not set by default any longer. Please check with your database vendor if you need assistance setting up your database values. Note that the manualCreation directive is set to true if you do not wish the tdk to create your database and tables. Set it to false to automatically build your sample application database. Turbine will still use the old database values in order to start up the application once you have completed building, so you do need both types of entries in your properties file. The following example will configure the tdk to build the sample newapp database for MySQL.
# ------------------------------------------------------------------- # D A T A B A S E S E T T I N G S # ------------------------------------------------------------------- database = mysql databaseDriver = org.gjt.mm.mysql.Driver databaseUrl = jdbc:mysql://localhost/newapp databaseUser = dbUser databasePassword = dbPassword databaseHost = localhost torque.database.name = newapp torque.database.manualCreation = false torque.database.driver = org.gjt.mm.mysql.Driver torque.database.createUrl = jdbc:mysql://localhost/newapp torque.database.buildUrl = jdbc:mysql://localhost/newapp torque.database.user = dbUser torque.database.password = dbPassword
5. Go to the directory "TDK_HOME/webapps/newapp/WEB-INF/build" and run the command "ant init". This command must be run before attempting to use the TDK. It creates the database tables and OM classes for accessing them.
NOTE
For Oracle and Sybase users it is often common that the database
has already been created: if this is the case then by setting the
torque.database.manualCreation property in your "build.properties"
file you can force the 'create-database' target to
be skipped.
6. Your first Turbine app has now been created! go back to the root directory of your TDK installation and type in "./bin/catalina.sh run" if you want to see console output or "./bin/catalina.sh start" if you want the servlet container process to run in the background.
NOTE
If you want automatic class reloading to work, then you have to
configure it specifically for each webapp that you generate.
If you use the the default setup, then class reloading will be
setup for you i.e. your APPNAME is 'newapp'. If, for example,
your APPNAME is 'rupert' then you must add the following to your
conf/server.xml file:
<context path="/rupert" docBase="rupert" reloadable="true"/>
Look for 'TDK SITE' in the conf/server.xml file and make the adjustment just above it to get class reloading working. You will see how the class reload has been setup for the default 'newapp' and you can use that as an example.
Now that you have your Turbine application created and running by following the instructions above, point your browser to http://SERVERNAME:8080/APPNAME/servlet/APPNAME where SERVERNAME is the hostname of the machine running Tomcat, and APPNAME is the name of the application you created.
The initial login screen should appear and you should login with username 'turbine' and password 'turbine' This will bring you to the initial "Turbine Data Manager" layout. From here you can insert/delete/edit entries in the default database or create and manage users using Flux, the built-in user management system for Turbine. These are the example turbine apps.
Look at the example app that you now have on your screen. The view that you are seeing actually consists of 4 different parts (top, bottom, menu and index) that were assembled for you on the fly by Velocity. In order to see how this works, you have to edit the file "webapps/APPNAME/templates/app/layouts/Default.vm" This file defines how the default layout is shown on your screen. As you can see, it is written as a fragment of HTML that will eventually be integrated into your final page. Editing this file will affect the layout of your entire application.
Knowing now how the page is laid out, go to the directory "webapps/APPNAME/templates/app/navigations" to see the files that will be inserted into the layout template above. Edit the file "DefaultBottom.vm", save your changes back, and reload your page. By doing this you should see whatever changes you have made to the file appear at the bottom of your layout. This change will also occur in all of the other pages on your site. Navigate to a different page in order to confirm this behavior.
Now go into the directory "webapps/APPNAME/templates/app/screens" The files in this directory are the ones that replace the "$screen_placeholder" variable in the original layout. Open up the file "Index.vm" and you will see that a variable is defined called "$headings" that holds the strings for each of the headings on the Index page and that a variable called "$entries" is used to show the dynamic data on the page. This variable comes from the Java class file that is associated with this .vm page, as explained in the next paragraph. The Index.vm page also includes a number of functions that begin with #, such as "#entryCell(...)" These functions are replaced with HTML fragments at runtime, as defined in the "webapps/APPNAME/templates/app/GlobalMacros.vm" file. Look at this file to get an idea of what each of these methods do. This file can be edited in order to add your own velocity macros to the system as well.
In order to view the Java file that is associated with the Index.vm, go to the directory "webapps/APPNAME/WEB-INF/src/java/PACKAGE/modules/screens" A quick look in this directory should show you that each page with dynamic data in it has an associated class file in this directory. Open the file "Index.java" and look over its contents. As you can see, the "doBuildTemplate" method creates a variable called "entries" and associates the data that it pulls from the database in the "getEntries" method into it. In the case of the Index.vm page, this corresponds to all of the entries from our example database. The "context.put("entries", getEntries())" method places the data and the associated handle for it into our session context so that it can be accessed from our Index.vm page. You would edit this file to change the behavior of a given page. More information on building sites with Velocity is available here.
Now go back into your sample app in your web browser and insert an entry into the table. Look at the URL line in your browser. The end of it should contain "/action/SQL" This is the method that Turbine just used to insert your data into the database. The class file corresponding to it can be found in "webapps/APPNAME/WEB-INF/src/java/PACKAGE/modules/actions" and is called SQL.java. In fact, when you did your Insert of the data, Turbine called a method called "doInsert" inside of the SQL class in order to insert the data. A full explaination of how actions work is available here.
Now that we know about actions, we should change our database to something more useful. In order to do this, move to the directory "webapps/APPNAME/WEB-INF/conf" and open up the file "APPNAME-schema.xml". This file contains our database schema in XML. This file should be rather self explainatory. Within it you can create new tables and new fields within existing tables. Add some more rows to the example table and save the file back. Now go to the directory "webapps/APPNAME/WEB-INF/build" and run the command "ant init" again. (WARNING: If this is done you will lose all of your data in the existing tables, do not run if you have data in your tables that you want to save.) This will update existing databases and their objects with new fields and create the databases defined in the .xml file, along with their associated java classes. The java classes that Turbine uses to access your database are located in the directory "webapps/APPNAME/WEB-INF/src/java/PACKAGE/om" Look at them to get an idea of how the object-model portion of Turbine operates. There should be one named after each of the tables that you defined above in your schema. These classes will be used to interact with the database while using Turbine.
After our schema has been updated we will need to go back and edit the .vm files that operate on it. Go back into "Index.vm" as described above and change the headings to those that match your new schema. If you have created another table that you would like to call from the Index, or have changed the name of your original table, edit your "Index.java" file to get the data from that Database instead of the default one by calling the OM object for it instead.
You now have your first Turbine application up and running and you now know how to edit the Java and .vm files in the TDK in order to begin building a specific application. In order to recompile any Java files that you change or create in the TDK, move to "webapps/APPNAME/WEB-INF/build" and run "ant compile". This will recompile all of the Java files that have changed in your project. You may also wish to join the Turbine Users mailing list. Instructions for doing so can be accessed via the Project Info page.
The TDK uses Tomcat 4.1 as it's Servlet container, but you can package up your webapps and run them under any compliant Servlet container. The only thing that you have to change are the references to the Servlet 2.3 DTDs in your web.xml file. If you change these references, webapps that you develop with the TDK should be fully portable. We use the Tomcat 4.1 server because it is the burgeoning standard.
We'll add more notes to this as the TDK gains more deployment features. There is a very primitive 'deploy' target, but all it currently does is package up your webapp in a WAR file.