<?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>
        <author email="rafal@apache.org">Rafal Krzewski</author>
    </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/engine">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>