http://www.greenninja.com/turbine/turbine-concepts.html
I'm adding it as an xdoc so people can update it as things change.
Jeff
<?xml version="1.0"?> <document>
<properties>
<title>Turbine Concepts</title>
<author email="[EMAIL PROTECTED]">Jeff Linwood</author>
</properties>
<body>
<section name="Turbine Concepts - Introduction">
<p>Looking for a modern web application architecture for your
Java development? Turbine is an open source server-side Java framework from
the Jakarta Apache project. Any recent servlet container can be used to run your
Turbine application. The developer distribution of Turbine (the TDK) includes
the servlet runner Tomcat 4.0, also from the Jakarta Apache project. Almost
any web application that uses persistence should also use a relational
database. Turbine supports most major commercial and open source relational
databases and provides an object-relational mapping layer, known as Torque. 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.</p>
<p>A quick guide to Turbine technologies:</p>
<ul>
<li>Presentation layer - Velocity or JSP</li>
<li>Database layer - Torque and Peers</li>
<li>Sample application - Flux</li>
<li>HTML Form Validation - Intake</li>
<li>Logging - Log4j and the Logging Service in Turbine 2</li>
<li>Services - Known as Fulcrum in Turbine 3</li>
</ul>
<p>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.</p>
<p>I'm going to explain how Turbine technology maps to MVC in
this article, after defining some core Turbine concepts. 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.</p>
</section>
<section name="How does Turbine fit in with other server side Java technologies">
<p>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.</p>
<p>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. Velocity is available from the Jakarta Apache
project, and is open source. I discuss how to choose between Velocity and JSP
for your project later in this article.</p>
<p>Turbine can be used with Enterprise Java Beans (EJB).
Turbine would be a client of your EJB system, just like a Swing application.
This is most useful if you already have a system built that uses Enterprise
Java Beans, or if parts of your system need to be distributed on different
servers. You would probably build a new Turbine service to access your EJB
system. Turbine does not require the use of EJB session or entity beans.</p>
</section>
<section name="Torque Object-Relational Persistence layer">
<p>Torque is a database persistence toolkit that Turbine uses. Most
open source and commercial relational databases are supported by Torque,
although you will generally have to supply your own JDBC driver. Torque can be
used by itself, in applications that don't use other Turbine classes. </p>
<p>Torque will have to be set up for use with your database. You
will have to specify the name of your project, the type of database you use,
and your JDBC connection parameters. </p>
<p>Your business objects will need to be modeled in XML to be
used with Torque. The project-schema.xml file will contain a description of
your database. You will need to describe your application's tables, columns,
indexes, and foreign keys. Generally, your business objects will map to a table,
and each field on the object will map to a column.</p>
<p>Torque can be used to generate primary key IDs for each
table in your database. Torque has three different choices for generating
IDs. The native method uses the internal unique ID generation facility of your
database. The idbroker method asks the Turbine IDBroker service for a unique
ID. The advantage of the idbroker method over the native method is that it is
not dependent on which database Turbine uses. Torque can also be told not to
generate any primary keys, with the none keyword.</p>
<p>Torque creates a SQL data schema for your database. For
some databases, Torque can execute this schema on your database to create the
tables for you. Torque also generates Java object source files for you. For
each table, Torque creates four different classes, two Peer classes and two
Data Object classes. One of the Peer classes and one of the Data Object
classes are Base classes. These are generated by Torque, and shouldn't be
edited. Instead, Torque provides you with two classes that extend each of the
Base classes. You should add your business logic to the subclasses. The Peer
classes correspond to the database table, and are static. The Data Object
classes represent an individual row of a table. The table columns become
JavaBean properties that can be used with standard getter and setter methods.</p>
</section>
<section name="Turbine Services">
<p>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. </p>
<p>Because each Service is used through an interface, Service
implementations are pluggable. This is extremely useful if you extend an
existing Service with your own functionality. All classes that use that
built-in Service will be able to use your new Service. </p>
<p>Almost every large Turbine project will need to create some
of its own Services. Your new Service should have an interface that extends the
Initable and Service interfaces. Your Service implementation class should
implement your interface and extend the TurbineBaseService class. The easiest
way to create a Service is taking an existing service that is close to what you
are trying to accomplish and rewriting the parts that don't fit. For instance,
if you were creating a SOAP Service, the XML-RPC Service that comes with
Turbine would be a good starting point.</p>
<p>Turbine comes with over 25 built-in Services. Here is a
brief overview of the some of the included Services:</p>
<ul>
<li>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 tedious code that maps HTML form parameters to
setter methods on a Bean is done for you. Intake is configured with a
single XML file.</li>
<li>UploadService - Manages file uploads from HTML widgets.</li>
<li>XSLTService - Transforms XML documents with XSLT
stylesheets. This service can cache compiled stylesheets for extra
performance.</li>
<li>>SecurityService - Manages users and permissions for
Turbine. I discuss this Service in more detail in the next section,
"Users and Security"</li>
</ul>
</section>
<section name="Users and Security">
<p>Turbine comes with a security model and several security
helper classes. In Turbine 2, the user security is contained in the
org.apache.turbine.services.security package and its sub-packages. </p>
<p>Turbine's security model has four interfaces:</p>
<ul>
<li>User</li>
<li>Group</li>
<li>Role</li>
<li>Permission</li>
</ul>
<p>The User interface is implemented by the TurbineUser class.
Each account in your application should be a TurbineUser object. </p>
<p>The Group is not a collection of users. Instead, the Group
is a resource or context that permissions are assigned to. Imagine that your
application has two different sections, User Administration and Server Administration.
Some users may be assigned permissions for one section, other users may be
assigned the same permissions for the other section. The Group allows you to
use the same permission name for different parts of the application.</p>
<p>The Role is a collection of Permissions. A Role can be made
up of more than one Permission object, and it is a convenient way to organize
Permissions. A good example would be an Administrator Role that contains Edit
User, Delete User, and Add User permissions. </p>
<p>The Permission controls access. Each individual action or
item in an application can be assigned a Permission. A User is granted a Permission
programmatically from within your Turbine code.</p>
</section>
<section name="Model View Controller (MVC)">
<p>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. </p>
<p>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 at <a
href="http://jakarta.apache.org/struts";>http://jakarta.apache.org/struts</a>.</p>
<p>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. </p>
<p>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.</p>
<p>The View in Turbine is the presentation layer, either
Velocity or JSP. In either case, no business logic should be embedded in the
View.</p>
<p>The Model contains the Peers or Services that you use for your
data source.</p>
<subsection name="Pull model of MVC">
<p>Turbine 2 supports the Pull Model for moving data between
the Model and the View. The Java programmers that work on the Model can
create objects called Tools 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.</p>
<p>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.</p>
</subsection>
<subsection name="Velocity or JSP">
<p>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.</p>
<p>My experience has been with JSP sites that weren't based on
Turbine, and with projects that used Velocity with Turbine. I feel that
Velocity is much simpler to work with than JSP, and you won't miss the extra
power that comes with JSP. One of the core tenets of the MVC design pattern is
that there shouldn't be any business logic in the View, and most guidelines for
JSP encourage the use of taglibs over Java scriptlets in your JSP. Velocity is
a templating language, and it is not possible to execute any embedded Java code
in your templates.</p>
</subsection>
</section>
<section>Getting Started</section>
<p>Turbine has a learning curve for new developers, but don't
let that discourage you from using it for your own projects.</p>
<p>The Turbine Developer Kit (TDK) contains everything you need
for getting started with Turbine except Ant and a JDBC-compliant database. Ant
is an open source Java build tool from the Jakarta Apache Project that Torque
requires. The Turbine source code can be downloaded from the same location as
the TDK. </p>
<p>Complete directions for getting Turbine up and running with
your database are included with the TDK distribution as /tdk/webapps/site/turbine-docs/howto/tdk-howto.html.</p>
<p>After you get Turbine running on your computer, explore the
Flux application installed with the TDK. Flux is a security application built
with Turbine that lets you manage Users, Groups, Roles, and Permissions. Because
the source code for Turbine is available, you can trace calls from Flux into
the Turbine framework.</p>
<p>You can decide whether to extend Flux for your application,
or whether it is better to build a Turbine application from scratch. If you need
user management functionality, it might be better to start with Flux.</p>
<p>After working with Turbine for a few minutes, a few hours,
or a few days = you're probably going to get stuck. The best thing to do is to
check out the Turbine mailing list archives, available in several locations.
Check the Jakarta Apache mailing list page below, as these archives change
frequently. You can also download complete copies of every mail sent to any
Jakarta Apache mailing list, in the MBOX format. This email archive format is
readable by most Unix mail programs, and Eudora on Windows. </p>
<p>Turbine-user is the name of the mailing list for developers
who are using the Turbine framework in their own applications. You may want to
subscribe yourself to this mailing list. The link to the Jakarta Apache mailing
lists is below. If you do post your question to the Turbine User list, your
best chance of getting a response is to include a descriptive title, a short
description of what you are trying to accomplish and what you tried, and small
snippets of any relevant code.</p>
<p>I hope you have fun working with Turbine!</p>
<section name="Further Reading">
<p>The Turbine web site is at <a
href="http://jakarta.apache.org/turbine";>http://jakarta.apache.org/turbine</a>.
The Turbine Developer Kit can be downloaded from this web site.</p>
<p>A very good tutorial on using Torque is also on the Turbine
web site, here <a href="http://db.apache.org/torque/tutorial.html";>http://jakarta.apache.org/turbine/torque/tutorial.html</a>.
</p>
<p>Velocity is available from <a
href="http://jakarta.apache.org/velocity";>http://jakarta.apache.org/velocity</a>.
Velocity is bundled inside the Turbine Developers Kit, so an extra download
isn't necessary.</p>
<p>The Jakarta Apache mailing lists for both Turbine and
Velocity are at <a href="http://jakarta.apache.org/site/mail.html";>http://jakarta.apache.org/site/mail.html</a>.
</p>
<p>Jeff Linwood has been using Turbine to build a web services
infrastructure application. He is a co-author of <a href="http://www.amazon.com/exec/obidos/ASIN/1861007817/ref=pd_ecc_rvi_1/002-4687840-3104031";>Professional Struts Applications</a>, 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.</p>
</section>
</body>
</document>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
