| <?xml version="1.0"?> |
| |
| <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> |
| </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 the <a |
| href="http://jakarta.apache.org/turbine/tdk/">Turbine Developer Kit</a> |
| (TDK). The TDK has everything that you need to get started with Turbine, |
| including the <a href="http://jakarta.apache.org/tomcat/">Tomcat Servlet |
| Engine</a> which is preconfigured to run Turbine. The TDK also has |
| sample applications as well as scripts that allow you to quickly build |
| your own application. As time progresses, we will be including more and |
| more helpful information in the TDK. Please see the |
| <a href="http://jakarta.apache.org/turbine/tdk/tdk-howto.html">Turbine |
| Development Kit Howto</a> for more information. |
| </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">funtional 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. For example, the Database Connection Pool is a service and so is |
| the Logging (which is backed by <a |
| href="http://jakarta.apache.org/log4j/">Log4J</a>). |
| </li> |
| <li> |
| org.apache.turbine.torque - Torque is our generic tool for building |
| autogenerated code. The benefit of this is that we are able to do things |
| like take a database that is defined as an XML file and then |
| autogenerate the .sql for a specific database as well as Java code that |
| can allow you to easily build an Object Relational system. |
| </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="http://jakarta.apache.org/site/mail.html">Turbine Mailing list</a>. |
| </p> |
| </section> |
| |
| </body> |
| </document> |