You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@turbine.apache.org by gk...@apache.org on 2017/11/22 13:04:41 UTC
svn commit: r1021216 [10/30] - in /websites/production/turbine/content: ./
common/ common/status/ css/ events/ further-reading/ reports/ turbine/
Modified: websites/production/turbine/content/fsd.html
==============================================================================
--- websites/production/turbine/content/fsd.html (original)
+++ websites/production/turbine/content/fsd.html Wed Nov 22 13:04:39 2017
@@ -1,745 +1,747 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.4 at 10 January 2016 -->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <title>Apache Turbine -
- Turbine Specification</title>
- <style type="text/css" media="all">
- @import url("./css/maven-base.css");
- @import url("./css/maven-theme.css");
- @import url("./css/site.css");
- </style>
- <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
- <meta name="Date-Revision-yyyymmdd" content="20160110" />
- <meta http-equiv="Content-Language" content="en" />
-
- </head>
- <body class="composite">
- <div id="banner">
- <a href="./" id="bannerLeft">
- <img src="images/turbine-project.png" alt="Apache Turbine" />
- </a>
- <div id="bannerRight">
- <img src="images/logo.gif" alt="Apache Turbine" />
- </div>
- <div class="clear">
- <hr/>
- </div>
- </div>
- <div id="breadcrumbs">
-
-
- <div class="xleft">
- <span id="publishDate">Last Published: 10 January 2016</span>
- | <span id="projectVersion">Version: 4.0</span>
- </div>
- <div class="xright"> <a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a>
- |
- <a href="./" title="Turbine">Turbine</a>
- |
- <a href="fulcrum/" title="Fulcrum">Fulcrum</a>
-
-
- </div>
- <div class="clear">
- <hr/>
- </div>
- </div>
- <div id="leftColumn">
- <div id="navcolumn">
-
-
- <h5>General Information</h5>
- <ul>
- <li class="none">
- <a href="index.html" title="Overview">Overview</a>
- </li>
- <li class="none">
- <a href="turbine-concepts.html" title="Turbine Concepts">Turbine Concepts</a>
- </li>
- <li class="none">
- <strong>Specification</strong>
- </li>
- <li class="none">
- <a href="further-reading/index.html" title="Further Reading">Further Reading</a>
- </li>
- <li class="none">
- <a href="news.html" title="News and Status">News and Status</a>
- </li>
- <li class="none">
- <a href="common/powered.html" title="Sites Using Turbine">Sites Using Turbine</a>
- </li>
- <li class="none">
- <a href="common/related.html" title="Sites Related to Turbine">Sites Related to Turbine</a>
- </li>
- <li class="none">
- <a href="common/license.html" title="License">License</a>
- </li>
- <li class="none">
- <a href="download.html" title="Download">Download</a>
- </li>
- <li class="none">
- <a href="examples.html" title="Example Apps">Example Apps</a>
- </li>
- </ul>
- <h5>Shortcuts to Turbine Documentation</h5>
- <ul>
- <li class="none">
- <a href="https://blogs.apache.org/turbine/" class="externalLink" title="Turbine Blog">Turbine Blog</a>
- </li>
- <li class="none">
- <a href="http://wiki.apache.org/turbine/" class="externalLink" title="Turbine Wiki Home">Turbine Wiki Home</a>
- </li>
- <li class="none">
- <a href="http://wiki.apache.org/turbine/Turbine2/FAQ" class="externalLink" title="Frequently Asked Questions (FAQ)">Frequently Asked Questions (FAQ)</a>
- </li>
- <li class="none">
- <a href="http://wiki.apache.org/turbine/Turbine2/Tutorial" class="externalLink" title="Tutorial">Tutorial</a>
- </li>
- <li class="none">
- <a href="http://wiki.apache.org/turbine/Turbine2/UsersGuide" class="externalLink" title="User's Guide">User's Guide</a>
- </li>
- <li class="none">
- <a href="http://wiki.apache.org/turbine/Turbine2/Development" class="externalLink" title="Development">Development</a>
- </li>
- </ul>
- <h5>Turbine Releases</h5>
- <ul>
- <li class="none">
- <a href="turbine/index.html" title="Overview">Overview</a>
- </li>
- <li class="none">
- <a href="turbine/turbine-2.3.3/index.html" title="Turbine 2.3.3">Turbine 2.3.3</a>
- </li>
- <li class="none">
- <a href="turbine/turbine-4.0-M2/index.html" title="Turbine 4.0-M2">Turbine 4.0-M2</a>
- </li>
- </ul>
- <h5>Turbine Development</h5>
- <ul>
- <li class="none">
- <a href="turbine/development/turbine-4.0/index.html" title="Turbine 4.0">Turbine 4.0</a>
- </li>
- </ul>
- <h5>Turbine Sub Projects</h5>
- <ul>
- <li class="none">
- <a href="fulcrum/index.html" title="Fulcrum">Fulcrum</a>
- </li>
- </ul>
- <h5>Closed projects</h5>
- <ul>
- <li class="none">
- <a href="stratum/index.html" title="Stratum">Stratum</a>
- </li>
- <li class="none">
- <a href="tdk/index.html" title="TDK">TDK</a>
- </li>
- <li class="none">
- <a href="meta/index.html" title="META">META</a>
- </li>
- </ul>
- <h5>Community</h5>
- <ul>
- <li class="none">
- <a href="who-we-are.html" title="Who we are">Who we are</a>
- </li>
- <li class="none">
- <a href="contact.html" title="Contact us">Contact us</a>
- </li>
- <li class="none">
- <a href="how-to-help.html" title="How to help">How to help</a>
- </li>
- <li class="none">
- <a href="how-it-works.html" title="How it works">How it works</a>
- </li>
- <li class="none">
- <a href="board-reports.html" title="Board reports">Board reports</a>
- </li>
- </ul>
- <h5>General Development Information</h5>
- <ul>
- <li class="none">
- <a href="common/code-standards.html" title="Coding Specification">Coding Specification</a>
- </li>
- <li class="none">
- <a href="common/developer-links.html" title="Developer Links">Developer Links</a>
- </li>
- <li class="none">
- <a href="common/documentation.html" title="Improving Documentation">Improving Documentation</a>
- </li>
- </ul>
- <h5>Project Documentation</h5>
- <ul>
- <li class="collapsed">
- <a href="project-info.html" title="Project Information">Project Information</a>
- </li>
- <li class="collapsed">
- <a href="project-reports.html" title="Project Reports">Project Reports</a>
- </li>
- </ul>
- <h5>Apache</h5>
- <ul>
- <li class="none">
- <a href="http://www.apache.org/" class="externalLink" title="Apache Website">Apache Website</a>
- </li>
- <li class="none">
- <a href="http://www.apache.org/licenses/" class="externalLink" title="License">License</a>
- </li>
- <li class="none">
- <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works">How the ASF works</a>
- </li>
- <li class="none">
- <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a>
- </li>
- <li class="none">
- <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a>
- </li>
- <li class="none">
- <a href="http://www.apache.org/security/" class="externalLink" title="Security">Security</a>
- </li>
- </ul>
- <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
- <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
- </a>
-
-
- </div>
- </div>
- <div id="bodyColumn">
- <div id="contentBox">
- <!-- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License. -->
-
-
-
-<div class="section">
-<h2>NOTE<a name="NOTE"></a></h2>
-
-
-<p>
-This specification was originally written for the Turbine 2.1
-release. While it still holds true for Turbine 2.3 in many parts, it
-might be outdated in details. It should serve to give you a
-"broad" view of the Turbine framework, not a detailed
-description how things work. Turbine 2.4 uses a very different
-concept, so this specification no longer applies to it.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Specification<a name="Specification"></a></h2>
-
-
-<p>
-Turbine is made up of five different modules which serve a specific
-service within the Turbine framework. In order for the reader to understand
-the general flow of the Turbine framework, each of these modules is explained
-in detail below.
-</p>
-
-
-<p>
-<center>
-<img src="images/Modules.gif" alt="" />
-</center>
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Action<a name="Action"></a></h2>
-
-
-<p>
-The Action module represents a chunk of code that performs task. For
-example, when a user submits an Html form, one of the hidden fields
-is which Action to execute in order to process the form information.
-The processing generally includes form validation as well as storing
-the form information into a database. The Page is responsible for
-executing the Action before the Screen is executed. That way, the
-Action can help determine which Screen is executed depending on the
-results of the Action.
-</p>
-
-
-<p>
-The process looks like this:
-</p>
-
-
-<table border="0" class="bodyTable">
-
-<tr class="a">
-
-<td>HTTP Client -></td>
-
-<td>Execute Turbine Servlet -></td>
-
-<td>Execute Page -></td>
-
-<td>Execute Layout/Screen/Navigation -></td>
-
-<td>Return Page Content</td>
-</tr>
-
-<tr class="b">
-
-<td></td>
-
-<td></td>
-
-<td align="center">If Action is defined then...</td>
-
-<td></td>
-
-<td></td>
-</tr>
-
-<tr class="a">
-
-<td></td>
-
-<td></td>
-
-<td>Execute Action</td>
-
-<td></td>
-
-<td></td>
-</tr>
-</table>
-
-
-<p>
-This model makes it really easy to separate the POST (GET works here as well)
-data processing into component modules that can be re-used. For instance, the
-Action "Logout" can be re-used from a number of different points in the system.
-It performs one single function and performs it well. The advantage of this type
-of behavior is that it prevents you from putting logic for handling form data
-into your servlets. This is great for those of you who want to integrate EJB's
-into Turbine because your Action's can simply make calls to your EJB's to process
-business logic.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Page<a name="Page"></a></h2>
-
-
-<p>
-The Page module is the first module in the chain of execution for
-the Page generation. It is considered to be the module which contains
-the rest of the modules (Action, Layout, Screen and Navigation).
-The Page module checks to see if there has been an Action defined in
-the request. If so, it attempts to execute that Action. After the
-Action has been executed, it asks the set Screen object for its Layout.
-Page then attempts to execute the Layout object which the Screen
-returned. Please note that the Action module can modify which Screen
-is executed. Also note that the Screen module has the option to
-override the Layout setting which defaults to "DefaultLayout." (Note:
-the DefaultLayout value is actually defined in the TurbineResources.properties
-file. This way, it is a simple property change instead of having to re-compile
-the Turbine code for your own purposes.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Screen<a name="Screen"></a></h2>
-
-
-<p>
-The Screen module is essentially considered the "body" of the webpage. The
-Layout module executes the Screen module. This is where the Html of the page is
-generated. <b>It is entirely possible to call external code here.</b> For
-example, you can call an EJB to provide you some business data which is then
-transformed using a tool such as <a class="externalLink" href="http://xml.apache.org/cocoon/">Cocoon</a> to render the business data
-into HTML which is then transfered to the client.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Navigation<a name="Navigation"></a></h2>
-
-
-<p>
-A website generally has a top and bottom navigation scheme. This is generally
-defined as the header and footer of the website. The Navigation is executed by
-the Layout. There may be multiple Navigation modules that the Layout executes
-(ie: the side, top and bottom parts of the page). Since it is generally common
-for multiple webpages to contain the same navigation, it is most common to
-define different Layouts for screens with very different Navigations. The
-advantage of using a system like this is that you can have multiple Navigations
-that are conditionally included and excluded in the Layout. Like Screens, the
-Navigation modules can also call out to external code, such as EJB's to get the
-business logic that is responsible for rendering the Html that is sent to the
-browser.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Layout<a name="Layout"></a></h2>
-
-
-<p>
-The Layout module is called from the Page module. This modules defines
-the physical Layout of a webpage. It generally defines the location of the
-Navigation portion (ie: the top and bottom part of the webpage) as well as
-the location of where the body (or Screen) of the page is. The
-Layout module executes the Screen module to build the body of the webpage.
-It executes the Navigation modules to build the portions of the webpage
-which define the navigation for the website.
-</p>
-
-
-<div class="section">
-<h2>Module object Encapsulation<a name="Module_object_Encapsulation"></a></h2>
-
-<p>
-<center>
-<img src="images/ModuleObjectLayout.gif" alt="" />
-</center>
-</p>
-
-</div>
-
-
-<p>
-
-<dt>From a module object encapsulation point of view, the image above represents
-how each of the modules fits into one another.</dt> For example, the Page module
-executes the Layout module, which then executes the Navigation and Screen
-modules. As one can see, this tends to appear how a templated Html page would
-look. This is no accident, the Turbine framework is essentially an object oriented
-representation of the components of an Html page.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Loaders<a name="Loaders"></a></h2>
-
-
-<p>
-<center>
-<img src="images/Loaders.gif" alt="" />
-</center>
-</p>
-
-
-<p>
-The loaders are responsible for dynamicially loading each of the five modules.
-These loaders have an option to cache the module objects in memory for extremely
-fast loading times.
-</p>
-
-
-<p>
-The loaders use intelligent factories in that we have added a property to
-TurbineResources.properties that allows you to define the "Loader Classpath". In
-other words, it is possible to physicially keep all of your web applications
-modules in their own package classpath and the loaders will be responsible for
-finding the right file to execute.
-</p>
-
-
-<p>
-This feature is great because it allows you to upgrade the core Turbine framework
-without having to make any modifications to your existing code! It also allows
-you to simply distribute your web application as a standalone system and then
-have your users download the Turbine framework as a separate requirement. Then,
-multiple web applications can be combined to form a complete system.
-</p>
-
-
-<p>
-<b>Note</b> that each of the modules must be multithread safe
-since multiple threads may try to execute a single module at the exact same time.
-These rules apply to general servlet programming so they are not that difficult
-to understand. The basic rule is to not try to define any class global variables
-within each of the modules unless it has been wrapped in a syncronized statement.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Factories<a name="Factories"></a></h2>
-
-<p>
-Each of the loaders mentioned makes use of one or more factories to create the
-different modules. By default the only factory that is enabled is the Java
-factory that creates requested modules from java class files.
-</p>
-
-
-<p>
-You can easily create your own factories by implementing a simple interface
-and registering them in the TurbineResource.properities. This allows you a lot
-of flexibility in the sense that you can load Turbine modules from <b>any
-</b> source that is able to provide you with a java object, for example an
-RMI server or scripting options like Rhino and JPython. Keep in mind that
-factories <b>must</b> be thread-save (the same applies to modules).
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>System Flow<a name="System_Flow"></a></h2>
-
-
-<p>
-When a new request comes in, the Turbine servlet first checks to make sure that
-a ServletAPI HttpSession object exists for the user making the request. If this
-HttpSession object does not exist, a Http redirect header is returned that
-redirects the browser to the "homepage" of the website (by default it is the
-"Login" screen and this can be configured via the TurbineResources.properties
-file). This redirect attempts to set a cookie that is unique for the visitor. If
-the cookie is not accepted, it will not be returned in the new request for the
-"homepage" and thus further session tracking will happen with modified URL's
-that contain the session information within them.
-</p>
-
-
-<p>
-<b>Note</b>: If you do not wish to require the user to login to the
-system with a username and password before executing the pages, then set the
-"Login" screen to be something else. This is done in the Turbine Servlet under
-the data.session.isNew() check. Until the user actually logs in, it is only possible
-to store temporary data for that users session. When the user logs in, it is
-possible to store permant information by simply putting data into a hashtable.
-The implementation of the User object (ie: TurbineUser) in the framework takes care
-of the issues involved with serializing that information to a resource such as a
-database or file on the hard disk.
-</p>
-
-
-<p>
-After a session with the user has been established, Turbine caches a few frequently
-used pieces of data in the RunData object. This object is created for each and
-every request and is passed around the system in order to provide all of the
-modules with access to request specific information such as a database
-connection, GET/POST/PATH_INFO (GPP) data (via the ParametersParser object), the
-Action and Screen names (made available from the GPP data), and the Document
-object where you put your Html output. The RunData object should never be stored
-in a global context because it is not multithread safe and each of the modules
-is expected to be multithread safe. Also, the RunData object may or may not
-contain information that should be persistent across requests.
-</p>
-
-
-<p>
-The Turbine servlet then checks to see if a user is attempting to Login to the
-system by looking at the defined Action and checking to see if the value is
-"LoginUser." If so, it will execute the "LoginUser" action (again, the action to
-execute here can be defined in the TurbineResources.properties file). Within this
-action, it is the coders responsibility to define the procedure for
-authenticating the user with the validateUser() method. This will probably mean
-validating the username and password against a database. The abstraction of
-Action modules makes it easily possible to have multiple authentication methods.
-</p>
-
-
-<p>
-Once the user has been validated (the RunData.save() method has been called) or
-not validated, then the SessionValidator action is executed from within the Turbine
-servlet. The SessionValidator action checks to see if a user has been logged in.
-If the user has not been logged in, then the Screen is set to be the "Login"
-screen. If not, then the users last access datestamp is updated. <b>If you would
-like to allow the user to view multiple pages without the need to login first,
-you will need to implement your own version of SessionValidator that just
-returns nothing as a result.</b> Then, for the pages that you will want to make
-secure, you should define a Layout that executes the SessionValidator action to
-make things secure. Then, your Screens should call that "secure" Layout.
-</p>
-
-
-<p>
-Next, the "DefaultPage" page is executed by the Turbine servlet. The "DefaultPage"
-starts a chain of events that eventually leads to a complete webpage
-development. First, the DefaultPage attempts to see if an Action has been
-defined. If so, then it attempts to execute that Action. See the definition of
-Action and Page above for more information. After the Action has been executed,
-the Screen is then asked for its Layout and the Layout is then executed.
-</p>
-
-
-<p>
-It is the Layouts responsibility to then execute the Navigation and requested
-Screen. After the Layout has executed its parts, it is finished and control is
-returned to the Turbine servlet which then sends out the page information.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Access Control Lists and User Permissions<a name="Access_Control_Lists_and_User_Permissions"></a></h2>
-
-
-<p>
-We have provided a beautiful system (because it is so simple and powerful) for
-controlling what a User is allowed to do and not allowed to do. It is based on
-the following concepts:
-</p>
-
-
-<p>
-One or more Roles are assigned to a User. A Role is a collection of one or more
-Permission's. The AccessControlList uses an AccessControlBuilder that
-allows you to determine whether or not a User has a Permission to do something
-or not.
-</p>
-
-
-<p>
-Thus, a User can have both the "Admin" and "Guest" Role. Within those Roles are
-the sets of Permissions that are allowed. In the "Admin" Role, one might have
-the Permission, "Edit Users". Then, it is simple to use the AccessControlList to
-check to see if the User has the permission "Edit Users" or if the User has the
-Role "Admin", in which case, it does not matter what the Permissions are.
-</p>
-
-
-<p>
-You will then use this system within any of modules to determine whether or
-not to execute some code. This will provide you with both a Page level of
-security (does the User have access to this page) as well as a Content level of
-security (does the User have access to see the content on this page, ie:
-hide/show content based on what Role the User is).
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Exception Handling<a name="Exception_Handling"></a></h2>
-
-
-<p>
-During execution, if at any time an exception is raised, the Turbine servlet
-catches that exception and attempts to execute the "DefaultPage" with the Screen
-set to be "Error". This is a simple debugging screen which displays a java stack
-trace as well as any CGI environment variables that have been set. It is
-possible to modify this Screen to display anything that you wish as well as
-define an alternative error screen within your web application via the
-TurbineResources.properties file. The idea is that all errors can be trapped in one
-location in order to make debugging as simple as possible as well as provide a
-consistent error interface to the users.
-</p>
-
-</div>
-
-
-<div class="section">
-<h2>Utility Code<a name="Utility_Code"></a></h2>
-
-
-<p>
-There is a number of utility classes included with Turbine.
-</p>
-
-
-<p>
-The Database pooling classes are helpful for defining the methods for obtaining
-a connection to the database. This code is implemented as a singleton system so
-that all you need to do is get an instance of the database class, get a
-connection and go. There is no need to pass around a Connection object. Turbine
-comes with pool implementations for many of the most popular databases. Creating
-your own is quite simple as well, all you need to do is look at the existing
-code and create your own. If you need help or want someone to create one for
-your database, simply ask on the mailing list.
-</p>
-
-
-<p>
-The *Peer classes are a great idea on how to abstract the database accesses so
-that all you need to do is pass in a Criteria object and execute doInsert(),
-doSelect(), doUpdate() or doDelete(). While not necessarily part of the Turbine
-framework, because each implementation is different depending on your needs, it
-is a great model to work from. Take a look at the TurbineUserPeer.java file for a
-good example of this methodology in use.
-</p>
-
-
-<p>
-The ParameterParser class takes all of the GET/POST/PATH_INFO data and parses it
-into a hashtable where it can be easily retrieved in a number of forms with the
-provided get* methods. This is how you can have access to form data that has
-been posted by a users web browser.
-</p>
-
-
-<p>
-The DynamicURI class should be used whenever a URI is needed within the system.
-Each portion of a URI can be defined in order to produce a custom URI that also
-includes the session tracking information if it exists. It is highly recommended
-that you use this class for generating all of your URI's for your application
-because it will allow you to easily add global functionality to your system.
-</p>
-
-
-<p>
-The DateSelector class generates Html popup menus for month/day/year. The beauty
-of this class is that you can provide a date for it to start with and it will
-automaticially generate the Html popups with that date.
-</p>
-
-
-<p>
-The Mail classes make it easy to send email via the JavaMail API's. These
-classes are just very simple classes and there is not a huge amount of
-functionality here. Essentially they allow you to get the job done and that is
-about it. Contributions to improve these classes are appreciated.
-</p>
-
-</div>
-
-
-
- </div>
- </div>
- <div class="clear">
- <hr/>
- </div>
- <div id="footer">
- <div class="xright">
- Copyright © 2000-2016
- <a href="http://turbine.apache.org/">Apache Software Foundation</a>.
- All Rights Reserved.
-
- </div>
- <div class="clear">
- <hr/>
- </div>
- </div>
- </body>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia Site Renderer 1.6 at 22 November 2017 -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Apache Turbine – Turbine Specification</title>
+ <style type="text/css" media="all">
+ @import url("./css/maven-base.css");
+ @import url("./css/maven-theme.css");
+ @import url("./css/site.css");
+ </style>
+ <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
+ <meta name="Date-Revision-yyyymmdd" content="20171122" />
+ <meta http-equiv="Content-Language" content="en" />
+
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="./" id="bannerLeft">
+ <img src="images/turbine-project.png" alt="Apache Turbine" />
+ </a>
+ <div id="bannerRight">
+ <img src="images/logo.gif" alt="Apache Turbine" />
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+ <div class="xleft">
+ <span id="publishDate">Last Published: 22 November 2017</span>
+ | <span id="projectVersion">Version: 4.0</span>
+ </div>
+ <div class="xright"> <a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a>
+ |
+ <a href="./" title="Turbine">Turbine</a>
+ |
+ <a href="fulcrum/" title="Fulcrum">Fulcrum</a>
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+ <h5>General Information</h5>
+ <ul>
+ <li class="none">
+ <a href="index.html" title="Overview">Overview</a>
+ </li>
+ <li class="none">
+ <a href="turbine-concepts.html" title="Turbine Concepts">Turbine Concepts</a>
+ </li>
+ <li class="none">
+ <strong>Specification</strong>
+ </li>
+ <li class="none">
+ <a href="further-reading/index.html" title="Further Reading">Further Reading</a>
+ </li>
+ <li class="none">
+ <a href="news.html" title="News and Status">News and Status</a>
+ </li>
+ <li class="none">
+ <a href="common/powered.html" title="Sites Using Turbine">Sites Using Turbine</a>
+ </li>
+ <li class="none">
+ <a href="common/related.html" title="Sites Related to Turbine">Sites Related to Turbine</a>
+ </li>
+ <li class="none">
+ <a href="common/license.html" title="License">License</a>
+ </li>
+ <li class="none">
+ <a href="download.html" title="Download">Download</a>
+ </li>
+ <li class="none">
+ <a href="examples.html" title="Example Apps">Example Apps</a>
+ </li>
+ </ul>
+ <h5>Shortcuts to Turbine Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="https://blogs.apache.org/turbine/" class="externalLink" title="Turbine Blog">Turbine Blog</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/turbine/" class="externalLink" title="Turbine Wiki Home">Turbine Wiki Home</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/turbine/Turbine2/FAQ" class="externalLink" title="Frequently Asked Questions (FAQ)">Frequently Asked Questions (FAQ)</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/turbine/Turbine2/Tutorial" class="externalLink" title="Tutorial">Tutorial</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/turbine/Turbine2/UsersGuide" class="externalLink" title="User's Guide">User's Guide</a>
+ </li>
+ <li class="none">
+ <a href="https://wiki.apache.org/turbine/Turbine5" class="externalLink" title="Development">Development</a>
+ </li>
+ </ul>
+ <h5>Turbine Releases</h5>
+ <ul>
+ <li class="none">
+ <a href="turbine/index.html" title="Overview">Overview</a>
+ </li>
+ <li class="none">
+ <a href="turbine/turbine-2.3.3/index.html" title="Turbine 2.3.3">Turbine 2.3.3</a>
+ </li>
+ <li class="none">
+ <a href="turbine/turbine-4.0-M2/index.html" title="Turbine 4.0-M2">Turbine 4.0-M2</a>
+ </li>
+ <li class="none">
+ <a href="turbine/turbine-4.0/index.html" title="Turbine 4.0">Turbine 4.0</a>
+ </li>
+ </ul>
+ <h5>Turbine Development</h5>
+ <ul>
+ <li class="none">
+ <a href="turbine/development/turbine-4.1/index.html" title="Turbine 4.1">Turbine 4.1</a>
+ </li>
+ </ul>
+ <h5>Turbine Sub Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="fulcrum/index.html" title="Fulcrum">Fulcrum</a>
+ </li>
+ </ul>
+ <h5>Closed projects</h5>
+ <ul>
+ <li class="none">
+ <a href="stratum/index.html" title="Stratum">Stratum</a>
+ </li>
+ <li class="none">
+ <a href="tdk/index.html" title="TDK">TDK</a>
+ </li>
+ <li class="none">
+ <a href="meta/index.html" title="META">META</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="who-we-are.html" title="Who we are">Who we are</a>
+ </li>
+ <li class="none">
+ <a href="contact.html" title="Contact us">Contact us</a>
+ </li>
+ <li class="none">
+ <a href="how-to-help.html" title="How to help">How to help</a>
+ </li>
+ <li class="none">
+ <a href="how-it-works.html" title="How it works">How it works</a>
+ </li>
+ <li class="none">
+ <a href="board-reports.html" title="Board reports">Board reports</a>
+ </li>
+ </ul>
+ <h5>General Development Information</h5>
+ <ul>
+ <li class="none">
+ <a href="common/code-standards.html" title="Coding Specification">Coding Specification</a>
+ </li>
+ <li class="none">
+ <a href="common/developer-links.html" title="Developer Links">Developer Links</a>
+ </li>
+ <li class="none">
+ <a href="common/documentation.html" title="Improving Documentation">Improving Documentation</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="project-info.html" title="Project Information">Project Information</a>
+ </li>
+ <li class="collapsed">
+ <a href="project-reports.html" title="Project Reports">Project Reports</a>
+ </li>
+ </ul>
+ <h5>Apache</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/" class="externalLink" title="Apache Website">Apache Website</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/licenses/" class="externalLink" title="License">License</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works">How the ASF works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/security/" class="externalLink" title="Security">Security</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License. -->
+
+
+
+<div class="section">
+<h2><a name="NOTE"></a>NOTE</h2>
+
+
+<p>
+This specification was originally written for the Turbine 2.1
+release. While it still holds true for Turbine 2.3 in many parts, it
+might be outdated in details. It should serve to give you a
+"broad" view of the Turbine framework, not a detailed
+description how things work. Turbine 2.4 uses a very different
+concept, so this specification no longer applies to it.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Specification"></a>Specification</h2>
+
+
+<p>
+Turbine is made up of five different modules which serve a specific
+service within the Turbine framework. In order for the reader to understand
+the general flow of the Turbine framework, each of these modules is explained
+in detail below.
+</p>
+
+
+<p>
+<center>
+<img src="images/Modules.gif" alt="" />
+</center>
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Action"></a>Action</h2>
+
+
+<p>
+The Action module represents a chunk of code that performs task. For
+example, when a user submits an Html form, one of the hidden fields
+is which Action to execute in order to process the form information.
+The processing generally includes form validation as well as storing
+the form information into a database. The Page is responsible for
+executing the Action before the Screen is executed. That way, the
+Action can help determine which Screen is executed depending on the
+results of the Action.
+</p>
+
+
+<p>
+The process looks like this:
+</p>
+
+
+<table border="0" class="bodyTable">
+
+<tr class="a">
+
+<td>HTTP Client -></td>
+
+<td>Execute Turbine Servlet -></td>
+
+<td>Execute Page -></td>
+
+<td>Execute Layout/Screen/Navigation -></td>
+
+<td>Return Page Content</td>
+</tr>
+
+<tr class="b">
+
+<td></td>
+
+<td></td>
+
+<td align="center">If Action is defined then...</td>
+
+<td></td>
+
+<td></td>
+</tr>
+
+<tr class="a">
+
+<td></td>
+
+<td></td>
+
+<td>Execute Action</td>
+
+<td></td>
+
+<td></td>
+</tr>
+</table>
+
+
+<p>
+This model makes it really easy to separate the POST (GET works here as well)
+data processing into component modules that can be re-used. For instance, the
+Action "Logout" can be re-used from a number of different points in the system.
+It performs one single function and performs it well. The advantage of this type
+of behavior is that it prevents you from putting logic for handling form data
+into your servlets. This is great for those of you who want to integrate EJB's
+into Turbine because your Action's can simply make calls to your EJB's to process
+business logic.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Page"></a>Page</h2>
+
+
+<p>
+The Page module is the first module in the chain of execution for
+the Page generation. It is considered to be the module which contains
+the rest of the modules (Action, Layout, Screen and Navigation).
+The Page module checks to see if there has been an Action defined in
+the request. If so, it attempts to execute that Action. After the
+Action has been executed, it asks the set Screen object for its Layout.
+Page then attempts to execute the Layout object which the Screen
+returned. Please note that the Action module can modify which Screen
+is executed. Also note that the Screen module has the option to
+override the Layout setting which defaults to "DefaultLayout." (Note:
+the DefaultLayout value is actually defined in the TurbineResources.properties
+file. This way, it is a simple property change instead of having to re-compile
+the Turbine code for your own purposes.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Screen"></a>Screen</h2>
+
+
+<p>
+The Screen module is essentially considered the "body" of the webpage. The
+Layout module executes the Screen module. This is where the Html of the page is
+generated. <b>It is entirely possible to call external code here.</b> For
+example, you can call an EJB to provide you some business data which is then
+transformed using a tool such as <a class="externalLink" href="http://xml.apache.org/cocoon/">Cocoon</a> to render the business data
+into HTML which is then transfered to the client.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Navigation"></a>Navigation</h2>
+
+
+<p>
+A website generally has a top and bottom navigation scheme. This is generally
+defined as the header and footer of the website. The Navigation is executed by
+the Layout. There may be multiple Navigation modules that the Layout executes
+(ie: the side, top and bottom parts of the page). Since it is generally common
+for multiple webpages to contain the same navigation, it is most common to
+define different Layouts for screens with very different Navigations. The
+advantage of using a system like this is that you can have multiple Navigations
+that are conditionally included and excluded in the Layout. Like Screens, the
+Navigation modules can also call out to external code, such as EJB's to get the
+business logic that is responsible for rendering the Html that is sent to the
+browser.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Layout"></a>Layout</h2>
+
+
+<p>
+The Layout module is called from the Page module. This modules defines
+the physical Layout of a webpage. It generally defines the location of the
+Navigation portion (ie: the top and bottom part of the webpage) as well as
+the location of where the body (or Screen) of the page is. The
+Layout module executes the Screen module to build the body of the webpage.
+It executes the Navigation modules to build the portions of the webpage
+which define the navigation for the website.
+</p>
+
+
+<div class="section">
+<h2><a name="Module_object_Encapsulation"></a>Module object Encapsulation</h2>
+
+<p>
+<center>
+<img src="images/ModuleObjectLayout.gif" alt="" />
+</center>
+</p>
+
+</div>
+
+
+<p>
+
+<dt>From a module object encapsulation point of view, the image above represents
+how each of the modules fits into one another.</dt> For example, the Page module
+executes the Layout module, which then executes the Navigation and Screen
+modules. As one can see, this tends to appear how a templated Html page would
+look. This is no accident, the Turbine framework is essentially an object oriented
+representation of the components of an Html page.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Loaders"></a>Loaders</h2>
+
+
+<p>
+<center>
+<img src="images/Loaders.gif" alt="" />
+</center>
+</p>
+
+
+<p>
+The loaders are responsible for dynamicially loading each of the five modules.
+These loaders have an option to cache the module objects in memory for extremely
+fast loading times.
+</p>
+
+
+<p>
+The loaders use intelligent factories in that we have added a property to
+TurbineResources.properties that allows you to define the "Loader Classpath". In
+other words, it is possible to physicially keep all of your web applications
+modules in their own package classpath and the loaders will be responsible for
+finding the right file to execute.
+</p>
+
+
+<p>
+This feature is great because it allows you to upgrade the core Turbine framework
+without having to make any modifications to your existing code! It also allows
+you to simply distribute your web application as a standalone system and then
+have your users download the Turbine framework as a separate requirement. Then,
+multiple web applications can be combined to form a complete system.
+</p>
+
+
+<p>
+<b>Note</b> that each of the modules must be multithread safe
+since multiple threads may try to execute a single module at the exact same time.
+These rules apply to general servlet programming so they are not that difficult
+to understand. The basic rule is to not try to define any class global variables
+within each of the modules unless it has been wrapped in a syncronized statement.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Factories"></a>Factories</h2>
+
+<p>
+Each of the loaders mentioned makes use of one or more factories to create the
+different modules. By default the only factory that is enabled is the Java
+factory that creates requested modules from java class files.
+</p>
+
+
+<p>
+You can easily create your own factories by implementing a simple interface
+and registering them in the TurbineResource.properities. This allows you a lot
+of flexibility in the sense that you can load Turbine modules from <b>any
+</b> source that is able to provide you with a java object, for example an
+RMI server or scripting options like Rhino and JPython. Keep in mind that
+factories <b>must</b> be thread-save (the same applies to modules).
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="System_Flow"></a>System Flow</h2>
+
+
+<p>
+When a new request comes in, the Turbine servlet first checks to make sure that
+a ServletAPI HttpSession object exists for the user making the request. If this
+HttpSession object does not exist, a Http redirect header is returned that
+redirects the browser to the "homepage" of the website (by default it is the
+"Login" screen and this can be configured via the TurbineResources.properties
+file). This redirect attempts to set a cookie that is unique for the visitor. If
+the cookie is not accepted, it will not be returned in the new request for the
+"homepage" and thus further session tracking will happen with modified URL's
+that contain the session information within them.
+</p>
+
+
+<p>
+<b>Note</b>: If you do not wish to require the user to login to the
+system with a username and password before executing the pages, then set the
+"Login" screen to be something else. This is done in the Turbine Servlet under
+the data.session.isNew() check. Until the user actually logs in, it is only possible
+to store temporary data for that users session. When the user logs in, it is
+possible to store permant information by simply putting data into a hashtable.
+The implementation of the User object (ie: TurbineUser) in the framework takes care
+of the issues involved with serializing that information to a resource such as a
+database or file on the hard disk.
+</p>
+
+
+<p>
+After a session with the user has been established, Turbine caches a few frequently
+used pieces of data in the RunData object. This object is created for each and
+every request and is passed around the system in order to provide all of the
+modules with access to request specific information such as a database
+connection, GET/POST/PATH_INFO (GPP) data (via the ParametersParser object), the
+Action and Screen names (made available from the GPP data), and the Document
+object where you put your Html output. The RunData object should never be stored
+in a global context because it is not multithread safe and each of the modules
+is expected to be multithread safe. Also, the RunData object may or may not
+contain information that should be persistent across requests.
+</p>
+
+
+<p>
+The Turbine servlet then checks to see if a user is attempting to Login to the
+system by looking at the defined Action and checking to see if the value is
+"LoginUser." If so, it will execute the "LoginUser" action (again, the action to
+execute here can be defined in the TurbineResources.properties file). Within this
+action, it is the coders responsibility to define the procedure for
+authenticating the user with the validateUser() method. This will probably mean
+validating the username and password against a database. The abstraction of
+Action modules makes it easily possible to have multiple authentication methods.
+</p>
+
+
+<p>
+Once the user has been validated (the RunData.save() method has been called) or
+not validated, then the SessionValidator action is executed from within the Turbine
+servlet. The SessionValidator action checks to see if a user has been logged in.
+If the user has not been logged in, then the Screen is set to be the "Login"
+screen. If not, then the users last access datestamp is updated. <b>If you would
+like to allow the user to view multiple pages without the need to login first,
+you will need to implement your own version of SessionValidator that just
+returns nothing as a result.</b> Then, for the pages that you will want to make
+secure, you should define a Layout that executes the SessionValidator action to
+make things secure. Then, your Screens should call that "secure" Layout.
+</p>
+
+
+<p>
+Next, the "DefaultPage" page is executed by the Turbine servlet. The "DefaultPage"
+starts a chain of events that eventually leads to a complete webpage
+development. First, the DefaultPage attempts to see if an Action has been
+defined. If so, then it attempts to execute that Action. See the definition of
+Action and Page above for more information. After the Action has been executed,
+the Screen is then asked for its Layout and the Layout is then executed.
+</p>
+
+
+<p>
+It is the Layouts responsibility to then execute the Navigation and requested
+Screen. After the Layout has executed its parts, it is finished and control is
+returned to the Turbine servlet which then sends out the page information.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Access_Control_Lists_and_User_Permissions"></a>Access Control Lists and User Permissions</h2>
+
+
+<p>
+We have provided a beautiful system (because it is so simple and powerful) for
+controlling what a User is allowed to do and not allowed to do. It is based on
+the following concepts:
+</p>
+
+
+<p>
+One or more Roles are assigned to a User. A Role is a collection of one or more
+Permission's. The AccessControlList uses an AccessControlBuilder that
+allows you to determine whether or not a User has a Permission to do something
+or not.
+</p>
+
+
+<p>
+Thus, a User can have both the "Admin" and "Guest" Role. Within those Roles are
+the sets of Permissions that are allowed. In the "Admin" Role, one might have
+the Permission, "Edit Users". Then, it is simple to use the AccessControlList to
+check to see if the User has the permission "Edit Users" or if the User has the
+Role "Admin", in which case, it does not matter what the Permissions are.
+</p>
+
+
+<p>
+You will then use this system within any of modules to determine whether or
+not to execute some code. This will provide you with both a Page level of
+security (does the User have access to this page) as well as a Content level of
+security (does the User have access to see the content on this page, ie:
+hide/show content based on what Role the User is).
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Exception_Handling"></a>Exception Handling</h2>
+
+
+<p>
+During execution, if at any time an exception is raised, the Turbine servlet
+catches that exception and attempts to execute the "DefaultPage" with the Screen
+set to be "Error". This is a simple debugging screen which displays a java stack
+trace as well as any CGI environment variables that have been set. It is
+possible to modify this Screen to display anything that you wish as well as
+define an alternative error screen within your web application via the
+TurbineResources.properties file. The idea is that all errors can be trapped in one
+location in order to make debugging as simple as possible as well as provide a
+consistent error interface to the users.
+</p>
+
+</div>
+
+
+<div class="section">
+<h2><a name="Utility_Code"></a>Utility Code</h2>
+
+
+<p>
+There is a number of utility classes included with Turbine.
+</p>
+
+
+<p>
+The Database pooling classes are helpful for defining the methods for obtaining
+a connection to the database. This code is implemented as a singleton system so
+that all you need to do is get an instance of the database class, get a
+connection and go. There is no need to pass around a Connection object. Turbine
+comes with pool implementations for many of the most popular databases. Creating
+your own is quite simple as well, all you need to do is look at the existing
+code and create your own. If you need help or want someone to create one for
+your database, simply ask on the mailing list.
+</p>
+
+
+<p>
+The *Peer classes are a great idea on how to abstract the database accesses so
+that all you need to do is pass in a Criteria object and execute doInsert(),
+doSelect(), doUpdate() or doDelete(). While not necessarily part of the Turbine
+framework, because each implementation is different depending on your needs, it
+is a great model to work from. Take a look at the TurbineUserPeer.java file for a
+good example of this methodology in use.
+</p>
+
+
+<p>
+The ParameterParser class takes all of the GET/POST/PATH_INFO data and parses it
+into a hashtable where it can be easily retrieved in a number of forms with the
+provided get* methods. This is how you can have access to form data that has
+been posted by a users web browser.
+</p>
+
+
+<p>
+The DynamicURI class should be used whenever a URI is needed within the system.
+Each portion of a URI can be defined in order to produce a custom URI that also
+includes the session tracking information if it exists. It is highly recommended
+that you use this class for generating all of your URI's for your application
+because it will allow you to easily add global functionality to your system.
+</p>
+
+
+<p>
+The DateSelector class generates Html popup menus for month/day/year. The beauty
+of this class is that you can provide a date for it to start with and it will
+automaticially generate the Html popups with that date.
+</p>
+
+
+<p>
+The Mail classes make it easy to send email via the JavaMail API's. These
+classes are just very simple classes and there is not a huge amount of
+functionality here. Essentially they allow you to get the job done and that is
+about it. Contributions to improve these classes are appreciated.
+</p>
+
+</div>
+
+
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ Copyright © 2000–2017
+ <a href="http://turbine.apache.org/">Apache Software Foundation</a>.
+ All rights reserved.
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
</html>
\ No newline at end of file