<?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>Turbine Getting Started</title>
  <author email="jon@latchkey.com">Jon S. Stevens</author>
  <author email="jvanzyl@apache.org">Jason van Zyl</author>
  <author email="seade@backstagetech.com.au">Scott Eade</author>
 </properties>

<body>

<section name="Getting Started">
<p>
The purpose of this document is to define simple documentation on
getting started with Turbine. For information about the overall
structure of Turbine, please refer to the <a href="fsd.html">Functional
Specification Document (FSD)</a> as well as the other documentation that
is available.
</p>

<p>
The first thing that you should do is download and install a Servlet Engine (e.g.
<a href="http://tomcat.apache.org/">Apache Tomcat</a> and
<a href="http://maven.apache.org/maven-1.x/">Maven 1</a>.  Then take a look at
the documentation for the <a href="http://turbine.apache.org/meta/">
Maven Environment for Turbine Application (M.E.T.A.)</a> plugin - it includes
details of how to set up a Turbine application.
</p>
</section>

<section name="Code Organization">
<p>
Turbine can be used in three different ways depending on what you need.
You can choose to only use one way or choose to use all three. It is up
to you.
</p>

<ul>
<li>As a servlet framework with Turbine as the controller.</li>
<li>As a framework of useful code in your application.</li>
<li>As a Object-Relational Tool.</li>
</ul>

<p>
In all cases, it means that you simply link against the API and code
provided in the turbine.jar file. In other words, if you want to only
use the Object Relational aspects of Turbine, then you would use Torque
to build your Object Relational code and then add the turbine.jar into
your classpath. Another example is if you want to use Turbine's
connection pool code. All you need to do is tell Turbine where its
configuration file is, add turbine.jar to your classpath and then add
the appropriate Turbine Java code into your application.
</p>

<p>
Turbine is now a fairly large codebase. This can be daunting to people
who are just starting out with Turbine. However, the code is fairly well
organized and as you learn about each part of the code, the entire
architecture starts to make sense and is really quite easy to master.
All of our code is well javadoc'd so we encourage you to review not only
the actual source code, but also the documentation. :-) The different
parts of Turbine are:
</p>

<ul>
<li>
org.apache.turbine.modules - This is where the code for the Modules
system is stored. The different Modules are described in more detail in
the <a href="fsd.html">functional specification document</a>.
</li>
<li>
org.apache.turbine.om - OM stands for Object Model. This is where the
code that represents Turbine's Object Model lives. The code in here is
for handling a lot of Turbine's RDBMS relationships. For example, there
is code that represents what a Turbine User is as well as code for the
BaseObject and BasePeer which is for the Peer based Object Relational
Tool.
</li>
<li>
org.apache.turbine.services - This is where the Services Framework
lives. The Services framework is a core aspect of Turbine. Essentially
it is a framework for creating Singleton objects which may also have an
init() and destroy() lifecycle. There are Services for many different
things.
</li>
<li>
org.apache.turbine.util - The Util package is just that. A package of
utility code that is used within Turbine. There is code that will allow
you to easily send template based email using WebMacro or Velocity as
well as many other commonly used web application tools.
</li>
</ul>
</section>

<section name="Standalone Usage">
<p>
Turbine can be easily used on its own. In order to do so, all you need
to do is something like this before you attempt to make a call to Turbine
based code:
</p>

<source>
TurbineConfig tc = new TurbineConfig("/path","TurbineResources.properties");
tc.init();
</source>

<p>
What that does is it tells Turbine the path to its configuration file
based on the relative path from "/path" (insert your own path). This is
held as a static in memory and therefore you only need to do it once.
You do not even have to worry about hanging on to the TurbineConfig
object. For more information, please see the javadoc for the
TurbineConfig object.
</p>
</section>

<section name="Further Questions and Comments">
<p>
If you have further questions or comments, please send them to the
<a href="mail-lists.html">Turbine Mailing list</a>.
</p>
</section>

</body>
</document>