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
