extensions/maven-plugin/xdocs/using_meta.xml - turbine-core - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 /*
  * Copyright 2001-2004 The Apache Software Foundation.
  *
  * Licensed 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>Using M.E.T.A.</title>
     <author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
   </properties>

   <body>

 <section name="Using M.E.T.A.">

 <subsection name="M.E.T.A. Modes">
 <p>
 The M.E.T.A. plugin can operate in different modes. Currently it supports the following modes:

 <ul>
 <li><b>normal</b> - Your application is developed outside the container tree. It must be deployed to the
 container by running the <a href="goals.html#turbine_deploy">turbine:deploy</a> goal.</li>
 <li><b>inplace</b> - The source code and the class files are kept together. Your web container will access
 the files in the development location and no explicit deployment to the container is necessary.
 This mode is similar to developing with the deprecated <a href="http://jakarta.apache.org/turbine/tdk/">Turbine Development Kit</a>.</li>
 </ul>

 Modes are discussed on the <a href="modes.html">Modes</a> page.</p>

 </subsection>

 <subsection name="Intended Development Cycles">

 <p>
 The goals of the M.E.T.A. plugin interact with many other goals from maven
 to create your build environment. As the function of some is not
 really intuitive, this is how the plugin is intended to be used:</p>
 <p>
 <source><![CDATA[
 Development cycle for java code
 ===============================

            [development start]
                    |
                    V
                maven turbine:setup - generate skeleton
                    |
                    V
 +----->  [application development]
 |                  |
 |                  V
 ^              maven java:compile  - compile code
 |                  |
 |                  V
 +-<-- yes <--- Errors / Test failures?
 |                  |
 ^                  |  no
 |                  V
 |        optional: maven turbine:deploy - deploy to container
 |           (not needed in "inplace" mode)
 |                  |
 |                  V
 ^          [In-container testing]
 |                  |
 |                  V
 +-<-- yes <--- Errors?
 |                  |
 ^                  |  no
 |                  V
 +-<-- no <---- Ready to ship?
                    |
                    | yes
                    V
                maven turbine:war - bind a war file
                    |
                    V
                Ship application
 ]]></source>
 </p>
 <p>
 <source><![CDATA[
 Development cycle for SQL code
 ==============================

             [development start]
                     |
                     V
                 maven turbine:setup - generate skeleton
                     |
                     V
                 maven torque:create-db - generate DB
                     |
                     V
  +----->  [application development]
  |                  |
  |                  V
  ^              maven turbine:sql - generate SQL code
  |                  |
  |                  V
  ^              maven torque:insert-sql - put SQL in DB
  |                  |
  |                  V
  +-<-- yes <--- Errors?
  |                  |
  ^                  |  no
  |                  V
  +-<-- no <---- Ready to ship?
                     |
                     | yes
                     V
     Ship files from target/sql directory
 ]]></source>
 </p>
 </subsection>
 </section>

 <section name="Preparing a new M.E.T.A. application">

 <subsection name="Ad hoc setup">
 <p>
 If you have tried out the &quot;helloworld&quot; example from the <a
 href="getting_started.html">Getting Started</a> page, then you already
 know that setting up a new Turbine-based application is just a single
 maven command away. We will refer to this as &quot;ad hoc&quot; setup,
 because you do not need to prepare anything before running the
 <a href="goals.html#turbine_setup">turbine:setup</a> goal.
 </p>

 <p>
 Ad hoc setup is best used if you plan on doing lots of customization
 work to your properties anyway or if you just need a quick skeleton to
 test out something or jot down a few classes. You simply provide the
 application name on the maven command line and M.E.T.A. sets up the rest
 for you using the plugin defaults.</p>

 <source><![CDATA[
 maven -Dturbine.app.name=<application name> turbine:setup
 ]]></source>

 <p>
 Note: In the subdirectory which contains your application skeleton,
 there will be a M.E.T.A. properties file, called <a href="config.html#setup_properties">setup.properties</a>. This is
 auto-generated by the plugin to make your setup reproducible.
 </p>
 </subsection>

 <subsection name="Custom setup">
 <p>
 Sometimes, ad hoc simply will not cut the cake. Then you need to
 prepare a properties file for the M.E.T.A. plugin called <a
 href="config.html#setup_properties">setup.properties</a>.  It must be
 placed in the directory where you will run the <a
 href="goals.html#turbine_setup">turbine:setup</a> goal. This
 properties file allows you to customize the layout of the new
 application.
 </p>

 <p>
 In the application skeleton is a new <a href="config.html#setup_properties">setup.properties</a>
 file created, which can be used to rebuild it by deleting all but this
 file from the directory tree and re-run <a
 href="goals.html#turbine_setup">turbine:setup</a>.
 </p>

 <p>
 You can change the name of the properties file with the <a
 href="properties.html#turbine_setup_properties">turbine.setup.properties</a>
 property:
 </p>
 <source><![CDATA[
 maven -Dturbine.setup.properties=helloworld.properties turbine:setup
 ]]></source>
 </subsection>

 <subsection name="OM Layers">
 <p>
 Turbine supports the retrieval of information from databases through
 various OM layers. The most popular is <a
 href="http://db.apache.org/torque/">Torque</a> and Turbine itself uses
 Torque for the <a
 href="http://jakarta.apache.org/turbine/turbine/turbine-2.3.1/services/security-service.html">Security
 Service</a> and the <a
 href="http://jakarta.apache.org/turbine/turbine/turbine-2.3.1/services/scheduler-service.html">Scheduler
 Service</a>. With the M.E.T.A. plugin, different OM layers can be
 configured. The default is to use Torque. The OM layer is configured
 by setting the <a
 href="properties.html#turbine_app_om_layer">turbine.app.om.layer</a>
 property. Currently supported settings are:<br/>

 <ul>
 <li>torque - Configure Torque</li>
 <li>none - don't use an OM layer</li>
 </ul>
 </p>
 </subsection>

 <subsection name="Demo pages">
 <p>
 In the &quot;helloworld&quot; example from the <a
 href="getting_started.html">Getting Started</a> page, you have seen
 that a newly generated turbine application already contains a few
 files which allow to check the correct setup. If you don't want
 M.E.T.A. to put these files into the skeleton, you can set the <a
 href="properties.html#turbine_app_setup_demo">turbine.app.setup.demo</a>
 property to false:
 </p>
 <source><![CDATA[
 maven -Dturbine.app.setup.demo=false turbine:setup
 ]]></source>
 </subsection>

 </section>

 <section name="Deploying your application with M.E.T.A.">
 <p>
 Application development happens in cycles of programming, compile and
 deploy. If you use an external web container, you deploy your compiled
 application into its <code>webapp</code> directory. If you have a
 local web container that you can customize, you might want to develop
 directly in the <code>webapp</code> directory and skip the
 deployment.<br/>
 </p>

 <subsection name="Deployment to a web container">
 <p>
 All your application code and Turbine support files are copied into a
 web container which is outside your development tree.  You must
 configure the appserver plugin (which also gives you the power to
 start and stop your container from maven. See the <a
 href="http://maven.apache.org/reference/plugins/appserver/">appserver
 plugin documentation</a> for more information) and its configuration
 is then used by M.E.T.A. The required appserver properties are listed
 on the <a href="properties.html">Properties Page</a>.
 </p>
 </subsection>

 <subsection name="Inplace Development">
 <p>
 Inplace development allows you to work directly on the files that are
 used by your web container.  Your application code and the Turbine
 support files are located in a directory which is accessed by the web
 container.
 </p>
 </subsection>
 </section>
 </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	/*
	* Copyright 2001-2004 The Apache Software Foundation.
	*
	* Licensed 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>Using M.E.T.A.</title>
	<author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
	</properties>

	<body>

	<section name="Using M.E.T.A.">

	<subsection name="M.E.T.A. Modes">
	<p>
	The M.E.T.A. plugin can operate in different modes. Currently it supports the following modes:

	<ul>
	<li><b>normal</b> - Your application is developed outside the container tree. It must be deployed to the
	container by running the <a href="goals.html#turbine_deploy">turbine:deploy</a> goal.</li>
	<li><b>inplace</b> - The source code and the class files are kept together. Your web container will access
	the files in the development location and no explicit deployment to the container is necessary.
	This mode is similar to developing with the deprecated <a href="http://jakarta.apache.org/turbine/tdk/">Turbine Development Kit</a>.</li>
	</ul>

	Modes are discussed on the <a href="modes.html">Modes</a> page.</p>

	</subsection>

	<subsection name="Intended Development Cycles">

	<p>
	The goals of the M.E.T.A. plugin interact with many other goals from maven
	to create your build environment. As the function of some is not
	really intuitive, this is how the plugin is intended to be used:</p>
	<p>
	<source><![CDATA[
	Development cycle for java code
	===============================

	[development start]
	\|
	V
	maven turbine:setup - generate skeleton
	\|
	V
	+-----> [application development]
	\| \|
	\| V
	^ maven java:compile - compile code
	\| \|
	\| V
	+-<-- yes <--- Errors / Test failures?
	\| \|
	^ \| no
	\| V
	\| optional: maven turbine:deploy - deploy to container
	\| (not needed in "inplace" mode)
	\| \|
	\| V
	^ [In-container testing]
	\| \|
	\| V
	+-<-- yes <--- Errors?
	\| \|
	^ \| no
	\| V
	+-<-- no <---- Ready to ship?
	\|
	\| yes
	V
	maven turbine:war - bind a war file
	\|
	V
	Ship application
	]]></source>
	</p>
	<p>
	<source><![CDATA[
	Development cycle for SQL code
	==============================

	[development start]
	\|
	V
	maven turbine:setup - generate skeleton
	\|
	V
	maven torque:create-db - generate DB
	\|
	V
	+-----> [application development]
	\| \|
	\| V
	^ maven turbine:sql - generate SQL code
	\| \|
	\| V
	^ maven torque:insert-sql - put SQL in DB
	\| \|
	\| V
	+-<-- yes <--- Errors?
	\| \|
	^ \| no
	\| V
	+-<-- no <---- Ready to ship?
	\|
	\| yes
	V
	Ship files from target/sql directory
	]]></source>
	</p>
	</subsection>
	</section>

	<section name="Preparing a new M.E.T.A. application">

	<subsection name="Ad hoc setup">
	<p>
	If you have tried out the "helloworld" example from the <a
	href="getting_started.html">Getting Started</a> page, then you already
	know that setting up a new Turbine-based application is just a single
	maven command away. We will refer to this as "ad hoc" setup,
	because you do not need to prepare anything before running the
	<a href="goals.html#turbine_setup">turbine:setup</a> goal.
	</p>

	<p>
	Ad hoc setup is best used if you plan on doing lots of customization
	work to your properties anyway or if you just need a quick skeleton to
	test out something or jot down a few classes. You simply provide the
	application name on the maven command line and M.E.T.A. sets up the rest
	for you using the plugin defaults.</p>

	<source><![CDATA[
	maven -Dturbine.app.name=<application name> turbine:setup
	]]></source>

	<p>
	Note: In the subdirectory which contains your application skeleton,
	there will be a M.E.T.A. properties file, called <a href="config.html#setup_properties">setup.properties</a>. This is
	auto-generated by the plugin to make your setup reproducible.
	</p>
	</subsection>

	<subsection name="Custom setup">
	<p>
	Sometimes, ad hoc simply will not cut the cake. Then you need to
	prepare a properties file for the M.E.T.A. plugin called <a
	href="config.html#setup_properties">setup.properties</a>. It must be
	placed in the directory where you will run the <a
	href="goals.html#turbine_setup">turbine:setup</a> goal. This
	properties file allows you to customize the layout of the new
	application.
	</p>

	<p>
	In the application skeleton is a new <a href="config.html#setup_properties">setup.properties</a>
	file created, which can be used to rebuild it by deleting all but this
	file from the directory tree and re-run <a
	href="goals.html#turbine_setup">turbine:setup</a>.
	</p>

	<p>
	You can change the name of the properties file with the <a
	href="properties.html#turbine_setup_properties">turbine.setup.properties</a>
	property:
	</p>
	<source><![CDATA[
	maven -Dturbine.setup.properties=helloworld.properties turbine:setup
	]]></source>
	</subsection>

	<subsection name="OM Layers">
	<p>
	Turbine supports the retrieval of information from databases through
	various OM layers. The most popular is <a
	href="http://db.apache.org/torque/">Torque</a> and Turbine itself uses
	Torque for the <a
	href="http://jakarta.apache.org/turbine/turbine/turbine-2.3.1/services/security-service.html">Security
	Service</a> and the <a
	href="http://jakarta.apache.org/turbine/turbine/turbine-2.3.1/services/scheduler-service.html">Scheduler
	Service</a>. With the M.E.T.A. plugin, different OM layers can be
	configured. The default is to use Torque. The OM layer is configured
	by setting the <a
	href="properties.html#turbine_app_om_layer">turbine.app.om.layer</a>
	property. Currently supported settings are:<br/>

	<ul>
	<li>torque - Configure Torque</li>
	<li>none - don't use an OM layer</li>
	</ul>
	</p>
	</subsection>

	<subsection name="Demo pages">
	<p>
	In the "helloworld" example from the <a
	href="getting_started.html">Getting Started</a> page, you have seen
	that a newly generated turbine application already contains a few
	files which allow to check the correct setup. If you don't want
	M.E.T.A. to put these files into the skeleton, you can set the <a
	href="properties.html#turbine_app_setup_demo">turbine.app.setup.demo</a>
	property to false:
	</p>
	<source><![CDATA[
	maven -Dturbine.app.setup.demo=false turbine:setup
	]]></source>
	</subsection>

	</section>

	<section name="Deploying your application with M.E.T.A.">
	<p>
	Application development happens in cycles of programming, compile and
	deploy. If you use an external web container, you deploy your compiled
	application into its <code>webapp</code> directory. If you have a
	local web container that you can customize, you might want to develop
	directly in the <code>webapp</code> directory and skip the
	deployment.<br/>
	</p>

	<subsection name="Deployment to a web container">
	<p>
	All your application code and Turbine support files are copied into a
	web container which is outside your development tree. You must
	configure the appserver plugin (which also gives you the power to
	start and stop your container from maven. See the <a
	href="http://maven.apache.org/reference/plugins/appserver/">appserver
	plugin documentation</a> for more information) and its configuration
	is then used by M.E.T.A. The required appserver properties are listed
	on the <a href="properties.html">Properties Page</a>.
	</p>
	</subsection>

	<subsection name="Inplace Development">
	<p>
	Inplace development allows you to work directly on the files that are
	used by your web container. Your application code and the Turbine
	support files are located in a directory which is accessed by the web
	container.
	</p>
	</subsection>
	</section>
	</body>
	</document>