xdocs/project-map.xml - turbine-core - Git at Google

 <?xml version="1.0"?>
 <!--
  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.
 -->

 <document>

     <properties>
         <title>Project Map</title>
     </properties>

     <body>

     <section name="Project Map">

     <p> On this page, you can find a functional breakdown of Turbine codebase.
     This should help you in getting familiar with the tools that Turbine offers
     to you. Also, it will help you locate people that are experts in the field
     of a specific functional block, so you can contact them if you encounter
     a problem, or better yet have made a patch that fixes it. </p>

     <p><a href="project-map/core.html"><b>Turbine Core</b></a></p>

     <p> In the Core part of Turbine you will find the Turbine Servlet, the
     single entry point to your application, and the classes that form the
     framework of HTTP-interfaced application following MVC design pattern.
     Here you will find the base classes you will have to extend to fill
     in the framework with your application's logic. See the
     <a href="fsd.html">specification</a> for more details. </p>

     <p><a href="project-map/essential.html"><b>Essential Services</b></a></p>

     <p> This block contains the <a href="services.html">Service Framework</a>
     that forms the basis of  Turbine infrastructure. It allows defining
     utility classes with pluggable implementation (that means that you
     can customize and  override the utility classes provided by Turbine
     easily) that can take part in the startup and shutdown sequence of the
     application. </p>

     <p><a href="project-map/content-generation.html"><b>Content generation services</b></a></p>

     <p> This block groups together various services that aid you in the process
     of creating the user interface of your application. Most important,
     you will find here services that provide <i>templating</i> functionality,
     that allows you to create the HTML/XML/WML presentation layer of your
     application independently form your Java sources. The services provided
     are actually wrappers around templating packages developed independently
     from Turbine, such as <a href="http://velocity.apache.org">Velocity</a>.
     Also, there is a service that allows you to use Sun's JSP technology for
     creating templates. Other services that fall into this block are
     the Pull service, allowing you to create tool boxes (read more about
     <a href="pullmodel.html">Pull model</a>), Localization service, that allows
     you to crate bundles of messages that your application displays translated
     into different languages, that can be easily manipulated, and the
     Upload service, that handles uploading files from HTML forms. </p>

     <p><a href="project-map/database.html"><b>Database access</b></a></p>

     <p> Database tools in Turbine include connection pooling service, which
     can transparently delegate to J2EE application server's pooling facilities,
     of provide connection pooling in lightweight, servlet container only
     environment. An important element you will find in this block is
     <a href="peers.html">Peers</a> framework, that is one of the corner stones
     of Turbine framework along with Services and Modules. Peers allow you to
     create relationship between tables in a relational database and classes in
     your application. It also allows to create queries in an Object-oriented way. </p>

     <p><a href="project-map/object-services.html"><b>Object services</b></a></p>

     <p> One of the greatest advantages of working in Java Servlets environment,
     is the statefullness of your application. You can create object and hold
     them in memory, to avoid repeated loading information form external
     sources, like disk files or the database. Turbine provides a few
     Services that will help you with management of these objects. One of them
     is Pool service that allows you to create pools of reusable object that
     may be acquired from the pool by a thread processing a request, and
     recycled when no longer needed. Cache service will help you with
     managing objects that contain information that can be reused multiple
     times. </p>

     <p><a href="project-map/auxilary-services.html"><b>Auxilary Services</b></a></p>

     <p> In this section you will find other services that might be useful
     in the building your application. For example
     <a href="http://www.xmlrpc.com">XMLRPC</a> service that allows
     communication between applications within a heterogenous environment
     using XML-based protocol over HTTP. There are also services allowing
     manipulation of XML content using XSLT, and a service that manages
     creating contexts for performing JNDI operations. </p>

     <p><a href="project-map/email.html"><b>E-mail messages</b></a></p>

     <p> Turbine can help you with creating and sending e-mail. Also
     with the help of templates, just as those you use for displaying
     HTML pages. </p>

     <p><a href="project-map/utility.html"><b>Utility classes</b></a></p>

     <p> This block encompasses the various utility classes contained in
     Turbine. You should check those classes, as they solve some common
     problems encountered in web application making. </p>

     <p><a href="project-map/tools.html"><b>Turbine tools</b></a></p>

     <p> In this block, you will find tools that ship together with Turbine.
     These tools are runnable from the command line, and are used for the
     development purposes, not during the normal operation of an application.

     The tools include <a href="howto/torque-howto.html">Torque</a>, the tool for
     generating Peer Framework classes for your application,
     <a href="services/intake-service.html">Intake</a> that generates classes for automation
     of processing of complex HTML forms. <!--, and the <a href="migrator.html">
     Migrator</a>, the tool that helps you with bringing your application
     up to date with newer releases of Turbine, by performing batches
     of search-and-replace operations on your sources. When used properly,
     it can save you a plenty of typing.--> </p>

     </section>

     <section name="Updating project map">

     <p> This section is meant for Turbine developers. </p>

     <p> Whenever you want to work on bringing the project map up to date, you
     should run the <code>update-classlist.sh</code> script contained in the
     <code>xdocs/project-map</code> directory. It will bring the <code>classlist</code>
     file, also in  that directory in sync with the Turbine source files.
     It will also create a  cvs diff of the <code>classlist</code> file and save the
     result into <code>changes</code> file. Open it and see the changes in the
     codebase between the last time the project map was updated, and the present.
     When you commit the modified xdocs, don't  forget to commit <code>classlist</code>
     file as well! </p>

     </section>

     </body>

 </document>
	<?xml version="1.0"?>
	<!--
	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.
	-->

	<document>

	<properties>
	<title>Project Map</title>
	</properties>

	<body>

	<section name="Project Map">

	<p> On this page, you can find a functional breakdown of Turbine codebase.
	This should help you in getting familiar with the tools that Turbine offers
	to you. Also, it will help you locate people that are experts in the field
	of a specific functional block, so you can contact them if you encounter
	a problem, or better yet have made a patch that fixes it. </p>

	<p><a href="project-map/core.html"><b>Turbine Core</b></a></p>

	<p> In the Core part of Turbine you will find the Turbine Servlet, the
	single entry point to your application, and the classes that form the
	framework of HTTP-interfaced application following MVC design pattern.
	Here you will find the base classes you will have to extend to fill
	in the framework with your application's logic. See the
	<a href="fsd.html">specification</a> for more details. </p>

	<p><a href="project-map/essential.html"><b>Essential Services</b></a></p>

	<p> This block contains the <a href="services.html">Service Framework</a>
	that forms the basis of Turbine infrastructure. It allows defining
	utility classes with pluggable implementation (that means that you
	can customize and override the utility classes provided by Turbine
	easily) that can take part in the startup and shutdown sequence of the
	application. </p>

	<p><a href="project-map/content-generation.html"><b>Content generation services</b></a></p>

	<p> This block groups together various services that aid you in the process
	of creating the user interface of your application. Most important,
	you will find here services that provide <i>templating</i> functionality,
	that allows you to create the HTML/XML/WML presentation layer of your
	application independently form your Java sources. The services provided
	are actually wrappers around templating packages developed independently
	from Turbine, such as <a href="http://velocity.apache.org">Velocity</a>.
	Also, there is a service that allows you to use Sun's JSP technology for
	creating templates. Other services that fall into this block are
	the Pull service, allowing you to create tool boxes (read more about
	<a href="pullmodel.html">Pull model</a>), Localization service, that allows
	you to crate bundles of messages that your application displays translated
	into different languages, that can be easily manipulated, and the
	Upload service, that handles uploading files from HTML forms. </p>

	<p><a href="project-map/database.html"><b>Database access</b></a></p>

	<p> Database tools in Turbine include connection pooling service, which
	can transparently delegate to J2EE application server's pooling facilities,
	of provide connection pooling in lightweight, servlet container only
	environment. An important element you will find in this block is
	<a href="peers.html">Peers</a> framework, that is one of the corner stones
	of Turbine framework along with Services and Modules. Peers allow you to
	create relationship between tables in a relational database and classes in
	your application. It also allows to create queries in an Object-oriented way. </p>

	<p><a href="project-map/object-services.html"><b>Object services</b></a></p>

	<p> One of the greatest advantages of working in Java Servlets environment,
	is the statefullness of your application. You can create object and hold
	them in memory, to avoid repeated loading information form external
	sources, like disk files or the database. Turbine provides a few
	Services that will help you with management of these objects. One of them
	is Pool service that allows you to create pools of reusable object that
	may be acquired from the pool by a thread processing a request, and
	recycled when no longer needed. Cache service will help you with
	managing objects that contain information that can be reused multiple
	times. </p>

	<p><a href="project-map/auxilary-services.html"><b>Auxilary Services</b></a></p>

	<p> In this section you will find other services that might be useful
	in the building your application. For example
	<a href="http://www.xmlrpc.com">XMLRPC</a> service that allows
	communication between applications within a heterogenous environment
	using XML-based protocol over HTTP. There are also services allowing
	manipulation of XML content using XSLT, and a service that manages
	creating contexts for performing JNDI operations. </p>

	<p><a href="project-map/email.html"><b>E-mail messages</b></a></p>

	<p> Turbine can help you with creating and sending e-mail. Also
	with the help of templates, just as those you use for displaying
	HTML pages. </p>

	<p><a href="project-map/utility.html"><b>Utility classes</b></a></p>

	<p> This block encompasses the various utility classes contained in
	Turbine. You should check those classes, as they solve some common
	problems encountered in web application making. </p>

	<p><a href="project-map/tools.html"><b>Turbine tools</b></a></p>

	<p> In this block, you will find tools that ship together with Turbine.
	These tools are runnable from the command line, and are used for the
	development purposes, not during the normal operation of an application.

	The tools include <a href="howto/torque-howto.html">Torque</a>, the tool for
	generating Peer Framework classes for your application,
	<a href="services/intake-service.html">Intake</a> that generates classes for automation
	of processing of complex HTML forms. <!--, and the <a href="migrator.html">
	Migrator</a>, the tool that helps you with bringing your application
	up to date with newer releases of Turbine, by performing batches
	of search-and-replace operations on your sources. When used properly,
	it can save you a plenty of typing.--> </p>

	</section>

	<section name="Updating project map">

	<p> This section is meant for Turbine developers. </p>

	<p> Whenever you want to work on bringing the project map up to date, you
	should run the <code>update-classlist.sh</code> script contained in the
	<code>xdocs/project-map</code> directory. It will bring the <code>classlist</code>
	file, also in that directory in sync with the Turbine source files.
	It will also create a cvs diff of the <code>classlist</code> file and save the
	result into <code>changes</code> file. Open it and see the changes in the
	codebase between the last time the project map was updated, and the present.
	When you commit the modified xdocs, don't forget to commit <code>classlist</code>
	file as well! </p>

	</section>

	</body>

	</document>