Fork me on GitHub

Turbine Concepts - Introduction

Looking for a modern web application architecture for your Java development? Turbine is an open source server-side Java framework from the Apache Software Foundation. Any servlet container supporting Servlet Specification 2.4 or better can be used to run your Turbine application.

We offer an easy-to use development environment using some Maven-Archetypes to quickly start developing Turbine applications. See the blog post in the Turbine Blog for usage information or Turbine Archetype Readme on GitHub.. If you want use Docker as developing environment, checkout docker branch, which is currently in experimental stage.

We offer an easy-to use development environment using some Maven-Archetypes to quickly start developing Turbine applications. See the blog post in the Turbine Blog for usage information.

Of course, the biggest advantage of Turbine is that it is free, and all of the source code is available to you, the application developer.

A quick guide to Turbine technologies:

  • Presentation layer - Velocity or JSP
  • Database layer - Turbine uses Torque, but different OM layers like OJB or Hibernate are also supported.
  • HTML Form Validation using the Turbine provided "Intake"-Service.
  • Logging - Turbine 5.0 uses Log4J2 with activated SLF4J-Binding. Internal Commons Logging is propagated using jcl-over-slf4j. Turbine 4.x and previous versions supported a wide range of logging frameworks like Log4J, jdk14 or simple file logging
  • Service based framework, using Avalon compatible components in Turbine 2.4 and beyond. Although this framework is stable it's not yet maintained anymore, and we may change it in the near future.

Applications built with Turbine are encouraged to follow the Model-View-Controller (MVC) architecture. In the Model-View-Controller design pattern, the Model is the business logic and stored data, the View is the user interface, and the Controller handles application flow and manages the Model and the Views.

The Turbine architecture encourages developers to separate business logic from presentation and application flow. If you use the Turbine framework, your code will be much easier to maintain as a result.

How does Turbine fit in with other server side Java technologies

The Turbine framework is a normal Java application that uses servlets for handling web users. It is meant to be run under a servlet container, and you can write your own custom servlets that load Turbine objects and access Turbine singletons.

Turbine's presentation layer can be used with Java Server Pages (JSP) or Velocity. Most Java developers working with web applications have some experience with JSP already. We discuss how to choose between Velocity and JSP for your project later on this page.

Turbine can be used with Enterprise Java Beans (EJB).Turbine would be a client of an EJB system, just like a Swing application. This is most useful if there is already a system that uses Enterprise Java Beans, or if parts of this system need to be distributed on different servers. A developer can build a new Turbine service to access the EJB system. Turbine does not require the use of EJB session or entity beans.

Turbine Services

Turbine Services are the back-end of the application framework. Each Turbine Service is implemented as a singleton class that can use Turbine's central configuration utility. These Services only have one state that all requesting clients share.

Because each Service is used through an interface, Service implementations are pluggable. This is extremely useful if extension of an existing Service with new functionality is needed . All classes that use that built-in Service will be able to use your new Service.

Starting with Turbine 2.4, the services are based on the Avalon framework. An avalon-based component can be plugged into the Turbine framework without any changes.

Turbine comes with a number of Services. These are bundled when using greater Turbine-2.3. Find out more about Fulcrum project!

Here is a brief overview of the some of the Services:

  • IntakeService - Provides web form validation and automatic mapping of data to a bean. All of your input forms can be easily validated, and all of the mapping of HTML form parameters to setter methods on a Bean is done automatically. Intake is configured with XML files.
  • UploadService - Manages file uploads from HTML widgets.
  • SecurityService - Manages users and permissions for Turbine. Turbine has a user, group, role, permission system which uses a database layer or LDAP as its backend.
  • JSONService - Provides a layer to Jackson 2 or Gson JSON bindings, which might be used for filtering or application wide settings.
  • XSLTService - Transforms XML documents with XSLT stylesheets. This service can cache compiled stylesheets for extra performance.

Model View Controller (MVC)

The Model View Controller (MVC) architecture allows the developer to separate presentation from business logic, which makes for more maintainable code. MVC has been used in traditional GUI programming for years, but most of the early web application architectures didn't take advantage of this separation.

Applications that use Java servlets can mix HTML into the Java code, requiring a recompile of the application if there are any look and feel changes. Sun corrected this problem by creating Java Server Pages (JSP), which are similar to Microsoft's Active Server Pages (ASP). An HTML designer can change the GUI without touching the Java code embedded into the JSP. Unfortunately, JSP doesn't have to conform to the MVC paradigm, so many applications were developed with business logic in the JSP pages. Several web application frameworks were created to bring MVC to the J2EE world, including Struts and Turbine. More information on Struts can be found on its web site.

One web application version of MVC is called Model 2. Sun created this term to describe J2EE applications that are built with a Controller servlet that manages interaction with the View JSPs and the back-end Model.

With Turbine, the Controller is the core TurbineServlet and the Action Event Handlers. Actions are used within Turbine to handle any user input that requires interaction with the Model. Turbine developers can assign different Actions to each input element in an HTML form. Actions aren't tied to a specific web page - if you have a common element such as a search form on multiple pages, you can use the same Action for each.

The View in Turbine is the presentation layer, either Velocity or JSP. In either case, no business logic should be embedded in the View.

The Model contains the Peers or Services that you use for your data source.

Pull model of MVC

Turbine supports the Pull Model for moving data between the Model and the View. The Java programmers that work on the Model can create Tool objects that expose the business logic and objects of the Model to the View. Every page or screen in the View will have access to the Tools. If the UI programmers that work on the Velocity or JSP files in the View want to move functionality inside the page or between pages, they don't need to get the Model developers to change any code. This is an extremely effective method of separating presentation from data.

Tool objects can follow the Facade design pattern of providing a single unified API for a complicated or disparate set of Model functionality. This provides a level of decoupling between the View and the underlying Model. If the Model definition changes, only the Tool will need to be modified, instead of every presentation page that uses that Model.

Velocity or JSP

Turbine gives developers a choice for which presentation language to use. Often times, this can be part of the requirements given to a development team. JSP is an established standard from Sun Microsystems, and there is a lot of momentum in the marketplace for JSP. From reading many anecdotal posts on the Turbine mailing lists, most developers that use Turbine prefer Velocity.

Getting Started

Turbine has a learning curve for new developers, but don't let that discourage you from using it for your own projects.

A typical Turbine development environment consists of Apache Maven and the Maven Environment for Turbine Applications (META). This helps you setting up, compiling and deploying your Turbine application to a web container. We recommend using Apache Tomcat as web container. If you want to use the database features of Turbine for security and scheduler, you also need a JDBC compliant database, e.g. MySQL, PostgreSQL or HSQL.

For deployment integration in an application server, a couple of tools exist, e.g. you may use the Cargo-Plugin.

After working with Turbine for a few minutes, a few hours, or a few days = you might get stuck. The best thing to do is to check out the Turbine mailing list archives. These are available for browsing using a web browser. If you are using Turbine on a regular base as developer or user, you should subscribe to one of the mailing lists.

The Turbine development team hopes, that you have fun working with Turbine!

Further Reading

The Turbine web site is at

A very good tutorial on using Torque is also on the Turbine web site, here

Velocity is available from There is also extensive documentation about the Syntax and Usage of the Velocity Template Language available.

The Turbine mailing lists.

This page

The original version of this page has been written by Jeff Linwood. He has been using Turbine to build a web services infrastructure application. He is a co-author of Professional Struts Applications, which covers Velocity. He'd like to thank Jason van Zyl, Troy Mutter, Skip Walker, David Minter, Jason Pettiss, and his brother Rob Linwood for reviewing this article.

The article has been revised for Turbine 2.3 and Turbine 2.4 by Henning Schmiedehausen. All errors and omissions from Jeffs' original article are mine.

More Changes since Turbine version 4 are done by