portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject svn commit: r678019 [2/3] - in /portals/jetspeed-2/portal/trunk: ./ applications/jetspeed-demo/ maven/ maven/jetspeed-mvn-maven-plugin/ maven/jetspeed-mvn-maven-plugin/src/ maven/jetspeed-mvn-maven-plugin/src/main/ maven/jetspeed-mvn-maven-plugin/src/m...
Date Fri, 18 Jul 2008 19:57:50 GMT
Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/building-jetspeed.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/building-jetspeed.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/building-jetspeed.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/building-jetspeed.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,207 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Building the Jetspeed-2 Portal Project from source</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Building the Jetspeed-2 Portal Project from source">
+      <p>
+        <em>Note: this documation page will eventually be moved to the main Jetspeed-2 Portal documentation</em> 
+      </p>
+      <p>
+        With the new <a href="jetspeed-mvn-plugin.html">jetspeed-mvn</a> plugin, building the Jetspeed-2 Portal itself from source
+        as well as building and deploying the default jetspeed-demo portal is now extremely easy.
+      </p>
+      <p>
+        After checking out the current source tree using svn from
+        <a href="http://svn.apache.org/repos/asf/portals/jetspeed-2/portal/trunk">http://svn.apache.org/repos/asf/portals/jetspeed-2/portal/trunk</a>,
+        only two local configuration changes are needed:
+        <ul>
+          <li>
+            Defining the Jetspeed-2 groupId as Maven pluginGroup, see the <a href="index.html">Introduction</a> page how to do that<br/>
+            <em>this only has to be done once as it is not related to the Jetspeed-2 codebase</em>
+          </li>
+          <li>
+            Creating your own local <strong><code>jetspeed-mvn-setttings.xml</code></strong> configuration in the root folder.
+          </li>
+        </ul>
+      </p>
+      <subsection name="Configuring the jetspeed-mvn-settings.xml">
+        <p>
+          All the settings needed during the build (and the jetspeed-demo Portal deployment) are isolated in one single file in the root folder
+          of the project: <strong><code>jetspeed-mvn-setttings.xml</code></strong>.
+        </p>
+        <p>
+          When you check out the Jetspeed-2 Portal source tree however, you'll notice that this file does not exist (yet).
+        </p>
+        <p>
+          The reason is that every developer has its own specific environment requirements and checking in one set of these most likely
+          won't work for someone else. And, when this file subsequently would need to be modified, you'll end up with a file flagged by subversion as
+          modified. 
+        </p>
+        <p>
+          The solution is simple: an existing <strong><code>jetspeed-mvn-setttings.xml</code></strong> file is marked with svn:ignore in subversion.
+        </p>
+        <p>
+          Now, everyone can create its own copy of this settings file without risk of it being accidentally commited.
+        </p>
+        <p>
+          To make it easy to create your own jetspeed-mvn-settings.xml, a sample file, <strong><code>jetspeed-mvn-setttings-sample.xml</code></strong>
+          is provided which you can simply copy to <strong><code>jetspeed-mvn-setttings.xml</code></strong> and modify only
+          the properties you'll need.
+        </p>
+        <p>
+          The <strong><code>jetspeed-mvn-setttings-sample.xml</code></strong> provides a default configuration using an Embbedded Derby database, and if that
+          suites you, probably the only changes needed will be for the location of the Derby database(s) and the deployment target directory for the
+          jetspeed-demo Portal:
+        <source><![CDATA[<properties>
+  ...      
+  <org.apache.jetspeed.server.home>@rootdir@/applications/jetspeed-demo/target/demo-deploy</org.apache.jetspeed.server.home>
+  ...
+  <org.apache.jetspeed.production.database.url>jdbc:derby:/tmp/derby/productiondb;create=true</org.apache.jetspeed.production.database.url>
+  <org.apache.jetspeed.test.database.url>jdbc:derby:/tmp/derby/testdb;create=true</org.apache.jetspeed.test.database.url>  
+  ...
+</properties>]]></source>
+          For example, <strong><code>/tmp</code></strong> on Linux might be restricted, and the target deployment folder for the jetspeed-demo probably
+          better point at a real <a href="http://tomcat.apache.org">Tomcat</a> installation.
+        </p>
+        <p>
+          <em>Note: required minimum version of Tomcat for the jetspeed-demo is now 5.5.26</em>
+        </p>
+      </subsection>
+      <subsection name="Optional: bootstrapping the build">
+        <p>
+          If, and only if, no (full) build of the source tree has been done yet, <em>and</em> you want to start with a full <em>test</em> build,
+          a subset of the build has to be performed <em>once</em> first:
+          <source>$mvn install -P init</source>
+          This will ensure the required Jetspeed-2 Maven plugins are build and installed as well as the jetspeed-portal-resources artifact.
+        </p>
+      </subsection>
+      <subsection name="Optional: running the test-cases during a build">
+        <p>
+          By default, running test-cases is disabled for Jetspeed-2 because it is very time-consuming and also requires the setup and initialization
+          of a dedicated test database <em><strong>every time</strong></em>!
+        </p>
+        <p>
+          But if you are a Jetspeed committer or otherwise would like to run the test-cases anyway, the following command is used to setup and
+          initialize the test database:
+          <source>$mvn jetspeed:mvn -Dtarget=testdb</source>
+          Thereafter, enabling the test-cases during a build is done by using profile <strong><code>test</code></strong>:
+          <source>$mvn install -P test</source>
+          But, to make it even a little more easier, another jetspeed:mvn target is provided which already combines the above two steps in one:
+          <source>$mvn jetspeed:mvn -Dtarget=test-install</source>
+          <em>
+            Running the test-cases requires (and only for this) the proper configuration of the org.apache.jetspeed.test.database.* properties
+            in jetspeed-mvn-settings.xml
+          </em>
+        </p>
+      </subsection>
+      <subsection name="building">
+        <p>
+          Performing a full build of all the Jetspeed-2 components, as well as the jetspeed-demo Portal is plain Maven-2 simple:
+          <source>$mvn install</source>
+        </p>
+      </subsection>
+      <subsection name="initializing the production database">
+        <p>
+          The production database configuration provided by the Jetspeed-2 Portal project itself is primarly intended to be used
+          by the developers using the jetspeed-demo Portal,
+        </p>
+        <p>
+          Manual initializing or reinitializing of the production database is done using the following command:
+          <source>$mvn jetspeed:mvn -Dtarget=proddb</source>
+          The above command however will <em>only</em> created the required database tables, <em>not</em> seed it with (demo) data,
+          for which the following command is needed:
+          <source>$mvn jetspeed:mvn -Dtarget=demo-seed</source>
+          As the above two commands usually goes together, the following command can be used instead to automatically invoke both:
+          <source>$mvn jetspeed:mvn -Dtarget=demo-db</source>
+        </p>
+      </subsection>
+      <subsection name="Using the jetspeed-demo Portal">
+        <p>
+          The jetspeed-demo Portal is an example custom Portal project used by the Jetspeed-2 committers for development and testing, but
+          can of course also be used as real "demo" for other purposes.
+        </p>
+        <p>
+          The full setup and usage of the jetspeed-demo Portal requires the following steps:
+          <table>
+            <tr>
+              <th>Task</th><th>Command</th>
+            </tr>
+            <tr>
+              <td>building and installing the jetspeed-demo war</td>
+              <td><source>$mvn jetspeed:mvn -Dtarget=demo-install</source></td>
+            </tr>
+            <tr>
+              <td>
+                database initialization and seeding<br/>
+                <em>see also previous section above</em>                
+              </td>
+              <td><source>$mvn jetspeed:mvn -Dtarget=demo-db</source></td>
+            </tr>
+            <tr>
+              <td>setting up a (clean) Tomcat server</td>
+              <td>
+                This requires downloading and installing your own <a href="http://tomcat.apache.org">Tomcat</a>
+                (<em>for Jetspeed-2.2 at least version 5.5.26 is now required!</em>)<br/>
+                Once you've installed Tomcat, adjust the <strong><code>org.apache.jetspeed.server.home</code></strong> property
+                in the jetspeed-mvn-settings.xml file to point at the installation directory.
+              </td>
+            </tr>
+            <tr>
+              <td>deploying the jetspeed-demo Portal</td>
+              <td><source>$mvn jetspeed:mvn -Dtarget=demo-deploy</source></td>
+            </tr>
+            <tr>
+              <td>performing everything above (except Tomcat installation) with a single command instead</td>
+              <td><source>$mvn jetspeed:mvn -Dtarget=demo</source></td>
+            </tr>
+            <tr>
+              <td>starting Tomcat</td>
+              <td><source>$ $TOMCAT_HOME/bin/catalina.sh run</source></td>
+            </tr>
+            <tr>
+              <td>Using the jetspeed-demo Portal</td>
+              <td>
+                <a href="http://localhost:8080/jetspeed">http://localhost:8080/jetspeed</a><br/><br/>
+                For login, use one of the following username/password combinations: admin/admin, user/user, jetspeed/jetspeed                
+              </td>
+            </tr>            
+          </table>            
+        </p>
+        <p>
+          There is one optional feature for building and deploying the jetspeed-demo Portal: storing and using PSML in the database.
+          This requires using an additional profile, dbpsml, during building the jetspeed-demo war as well as slightly different jetspeed:mvn targets to execute.
+          To execute all of that with one command, use:
+          <source>$mvn jetspeed:mvn -Dtarget=demo-dbpsml</source>
+          instead of using the -Dtarget=demo as shown above.
+        </p>
+        <p>
+          Further detail of the different jetspeed:mvn targets and configurations used for the dbpsml demo can be found in the jetspeed-mvn-plugin configuration
+          within the root pom.xml.  
+        </p>
+      </subsection>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/building-jetspeed.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/building-jetspeed.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/jetspeed-demo.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/jetspeed-demo.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/jetspeed-demo.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/jetspeed-demo.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,33 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Example Jetspeed-2 Maven build configuration: The default Jetspeed Demo Portal</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Configuration and usage of the default Jetspeed Demo Portal">
+      <p>
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/jetspeed-demo.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/jetspeed-demo.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/multiple-targets.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/multiple-targets.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/multiple-targets.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/multiple-targets.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,33 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Example Jetspeed-2 Maven build and configuration: Handling multiple target environments</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Handling multiple target environments">
+      <p>
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/multiple-targets.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/examples/multiple-targets.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/index.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/index.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/index.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,115 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Building and developing Jetspeed-2 using Maven-2</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Introduction">
+      <p>
+        The Jetspeed-2 build system is, as of version 2.2, fully based upon <a href="http://maven.apache.org">Apache Maven 2.0</a>.
+      </p>
+      <p>
+        This means the Jetspeed project developers as well as custom portal developers and system integrators are provided with a standardized and very
+        pluggable and configurable build environment which follows the standard guidelines of the Maven 2 build framework.
+      </p>
+      <p>
+        The Jetspeed-2 Portal itself is an application based upon a very flexible component architecture which is "assembled" and configured at runtime using
+        <a href="http://www.springframework.org">Spring Framework</a>.
+        One of the primary features of Jetspeed-2 Portal is that it can be adapted and configured for very divers and specific requirements. To be able to <em>leverage</em>
+        this feature for custom portal projects, configuring how Jetspeed-2 is to be assembled and integrated for the target environment(s) requires a very flexible build and
+        configuration toolset as well.
+      </p>
+      <subsection name="Maven Plugins">
+        <p>
+          The "standard" Maven-2 toolset is capable enough to <em>build</em> and <em>dynamically resolve</em>
+          most components and artifacts needed for a (custom) Jetspeed-2 Portal. But <em>configuring</em> and <em>integrating</em> Jetspeed-2 within <em>your</em>
+          specific project environment usually goes far beyond just <em>building</em>.
+        </p>
+        <p>
+          Setting up and interacting with back-end databases, creating and maintaining portal configurations for a specific target deployment environment, and
+          deploying not only "just" a portal war but everything required at runtime, is mostly "out-of-scope" of the standard Maven-2 toolset.
+        </p>
+        <p>
+          To be able to meet the myriad of possible integration requirements (from a Jetspeed-2 project POV) and still leverage the Maven 2 toolset, a few custom
+          Maven "plugins" have been written providing features like database initialization, portal configuration and portal deployment which can be configured
+          and used within a standard Maven 2 build environment.          
+        </p>
+        <p>
+          The rationale for the main Jetspeed Maven Plugin, jetspeed:mvn, orchestrating the usage of the other Jetspeed plugins is described in
+          <a href="the-need-for-a-custom-lifecycle.html">The Need for a custom Maven lifecycle</a>. 
+        </p>
+        <p>
+          Detailed documentation and configuration of each of the Maven plugins is available from the <a href="jetspeed-maven-plugins.html">Jetspeed Maven Plugins Overview</a>
+          menu and its subpages. Example usages and build instructions for Jetspeed-2 (which leverages these plugins too) are also available from the side menu.
+        </p>
+      </subsection>
+      <subsection name="Maven Archetypes">
+        <p>
+          As will become clear from the more detailed descriptions and their usages provided with each plugin, manually
+          setting up and configuring a complete (custom) Jetspeed Portal project is far from trivial and requires quite a few steps to perform.
+        </p>
+        <p>
+          The basic <a href="project-structure.html">project structure and configuration</a> however will be in most cases the same,
+          and a standard way of setting up such an initial build project configuration is using a Maven archetype plugin.
+          Jetspeed-2 provides its own jetspeed-archetype Maven plugin which can be used as a quickstart for creating a new custom portal project.
+          Detailed description and usage for the Jetspeed-2 Archetype plugin is provided <a href="jetspeed-archetype.html">here</a>.
+        </p>
+      </subsection>
+      <subsection name="IMPORTANT: required configuration of the Maven Settings pluginGroups">
+        <p>
+          Using non standard Maven Plugins (e.g. not from the Maven or CodeHaus Plugin projects) from the command line by default requires one to specify the full
+          coordinates of the intended plugin goal.
+        </p>
+        <p>
+          For the Jetspeed-2 Maven Plugins, this would mean for example for invoking the <a href="jetspeed-mvn-plugin.html">jetspeed:mvn</a> plugin something like:
+          <source>$mvn org.apache.portals.jetspeed-2:jetspeed:mvn -Dtarget=demo</source>
+        </p>
+        <p>
+          However this can be simplified by telling Maven which additional plugin groups it should search through when the groupId is not specified on the command.<br/>
+          See also the main documentation for the <a href="http://maven.apache.org/settings.html">Maven Settings</a>.
+        </p>
+        <p>
+          Adding the Jetspeed-2 Maven Plugins groupId to the pluginGroups in your Maven settings.xml is therefore recommended and assumed by all example usages given
+          throughout the Jetspeed-2 documentation. 
+        </p>
+        <p>
+          The current user Maven settings.xml can be found at: <strong><code>${user.home}/.m2/settings.xml</code></strong> (create one if it doesn't exist yet).
+        </p>
+        <p>
+          The Jetspeed-2 groupId should be added to the pluginGroups within the settings.xml as follows:
+        <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/POM/4.0.0">
+  <pluginGroups>
+    <pluginGroup>org.apache.portals.jetspeed-2</pluginGroup>
+    ...
+  </pluginGroups>
+  ...
+</settings>]]></source>
+          Once the above pluginGroup is configured, the same example from above can be shorted as follows:
+          <source>$mvn jetspeed:mvn -Dtarget=demo</source>            
+        </p>
+      </subsection>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/index.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/index.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-archetype.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-archetype.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-archetype.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-archetype.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,33 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Quickstart a new custom Jetspeed Portal project using the jetspeed-archetype Maven Plugin</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Using the jetspeed-archetype Maven Plugin">
+      <p>
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-archetype.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-archetype.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-ddl-plugin.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-ddl-plugin.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-ddl-plugin.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-ddl-plugin.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,33 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Configuration and usage of the jetspeed-db:ddl Maven Plugin</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Configuration and usage of the jetspeed-db:ddl Maven Plugin">
+      <p>
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-ddl-plugin.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-ddl-plugin.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-init-plugin.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-init-plugin.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-init-plugin.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-init-plugin.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,44 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Configuration and usage of the jetspeed-db:init Maven Plugin</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Configuration and usage of the jetspeed-db:init Maven Plugin">
+      <p>
+        The jetspeed-db:init Maven Plugin is capable of performing many database related tasks for initializing a (Jetspeed Portal) production database
+        but can also be used for setting up database data needed for unit tests during an (integration) test build.          
+      </p>
+      <p>
+        The following <em>independent</em> tasks can be configured:
+        <ul>
+          <li>unpacking of (remote) resource archives, like database (ddl) sql scripts</li>
+          <li>executing selected sql scripts against the a database</li>
+          <li>executing the jetspeed-serializer component for initializing a Jetspeed Portal database</li>
+          <li>executing the jetspeed-serializer component for loading Jetspeed PSML in a database</li>
+        </ul> 
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-init-plugin.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-db-init-plugin.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-deploy-plugin.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-deploy-plugin.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-deploy-plugin.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-deploy-plugin.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,33 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Configuration and usage of the jetspeed-deploy:deploy Maven Plugin</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Configuration and usage of the jetspeed-deploy:deploy Maven Plugin">
+      <p>
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-deploy-plugin.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-deploy-plugin.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-maven-plugins.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-maven-plugins.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-maven-plugins.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-maven-plugins.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,74 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Overview of the Jetspeed Maven Plugins</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Overview of the Jetspeed Maven Plugins">
+      <p>
+        The <a href="http://maven.apache.org">Maven 2.0</a> plugins provided by Jetspeed-2 are used for three different purposes:
+      </p>
+      <ul>
+        <li>Adding support for standard artifact (mainly: war) building:
+          <ul>
+            <li>the <a href="jetspeed-unpack-plugin.html">jetspeed-unpack:unpack</a> Plugin</li>
+            <li>the <a href="jetspeed-deploy-plugin.html">jetspeed-deploy:deploy</a> Plugin</li>
+         </ul> 
+        </li>
+        <li>Performing target environment integration tasks performed outside the standard artifact building lifecycle:
+          <ul>
+            <li>the <a href="jetspeed-db-init-plugin.html">jetspeed-db:init</a> Plugin</li>
+            <li>the <a href="jetspeed-deploy-plugin.html">jetspeed-deploy:deploy</a> Plugin</li>
+         </ul> 
+        </li>
+        <li>Automating and coordinating integration tasks to be performed outside the standard artifact building lifecycle:
+          <ul>
+            <li>the <a href="jetspeed-mvn-plugin.html">jetspeed:mvn</a> Plugin</li>
+         </ul> 
+        </li>
+        <li>Jetspeed Portal Project (internal) build support for generating database ddl script from ddl schema definitions:
+          <ul>
+            <li>the <a href="jetspeed-db-ddl-plugin.html">jetspeed-db:ddl</a> Plugin</li>
+         </ul> 
+        </li>
+      </ul>
+      <p>
+        Additionally, Jetspeed-2 provides an project archetype for usage with the
+        <a href="http://maven.apache.org/plugins/maven-archetype-plugin/">Maven 2 Archetype Plugin</a>,
+        the <a href="jetspeed-archetype.html">jetspeed-archetype</a>.
+      </p>
+      <p>
+        The jetspeed-archetype is a resource for the Maven Archetype plugin to generate a new custom <a href="project-structure.html">Jetspeed Portal project structure</a>
+        with a basic configuration to effectively make use of the Jetspeed-2 Maven Plugins.
+      </p>
+      <subsection name="Recommended reading">
+        <p>
+          The rationale for automating Maven 2 using the jetspeed:mvn Maven Plugin and coordinating execution of integration tasks
+          outside the standard artifact building lifecycle is described in: <br/>
+          <pre>&#160;&#160;&#160;<a href="the-need-for-a-custom-lifecycle.html">The need for a custom Maven Lifecycle</a></pre>.
+        </p>
+      </subsection>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-maven-plugins.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-maven-plugins.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-mvn-plugin.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-mvn-plugin.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-mvn-plugin.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-mvn-plugin.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,591 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>Automating Maven project builds using the jetspeed:mvn Maven Plugin</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="Automating Maven project builds using the jetspeed:mvn Maven Plugin">
+      <p>
+        The jetspeed:mvn Maven Plugin is a general purpose plugin for automating and coordinating specific integration tasks using the Maven build environment
+        itself. This plugin provides support for "running" one or more custom Maven project build definitions using predefined set of goals, profiles, Maven settings
+        and runtime properties.
+      </p>
+      <p>
+        The rationale for running custom Maven project build definitions <em>besides</em> the standard Maven project definitions and build
+        lifecycle is described in <a href="the-need-for-a-custom-lifecycle.html">The need for a custom Maven lifecycle</a>.
+      </p>
+      <p>
+        The jetspeed:mvn plugin is based upon and adapted from the standard <a href="http://maven.apache.org/plugins/maven-invoker-plugin/">Maven Invoker Plugin</a>,
+        which is (only) targetted at running integration test projects as attached to the integration-test lifecycle phase.
+      </p>
+      <p>
+        The jetspeed:mvn expands upon the Invoker Plugin by allowing to be invoked directly from the commandline as well as providing a more generic and
+        configurable <em>chain</em> of execution targets, similar to <a href="http://ant.apache.org">Apache Ant</a> build scripts, but fully using and
+        delegating to standard Maven-2 project build lifecycle handling for the actually execution of the individual target tasks.
+      </p>
+      <p>
+        Other than allowing execution from the commandline and the enhanced configuration options, the jetspeed:mvn doesn't really provide new behavior
+        compared to the standard Maven Invoker Plugin and uses the same Maven API and components (the shared maven-invoker component).
+      </p>
+      <p>
+        This plugin doesn't depend in any way on Jetspeed-2 itself and as such is equally usable for other type of projects with similar need for
+        performing tasks <em>besides</em> the normal Maven build lifecycle. Additionally, this plugin can also be used for "just" automating the standard
+        Maven build tasks accross multiple projects using the Apache Ant like chained target definition configurations.   
+      </p>
+    </section>
+    <section name="Quick Overview">
+      <p>
+        The jetspeed:mvn plugin when invoked will execute a single target task defined in its plugin configuration. But, because a target can have a "depends"
+        configuration itself, this might actually result in a chain of targets to be executed up the originally specified target itself.
+      </p>
+      <p>
+        This is a listing of all the elements which can be configured for the jetspeed:mvn plugin:
+      </p>
+      <p>
+        <source><![CDATA[<plugin>
+  <groupId>org.apache.portals.jetspeed-2</groupId>
+  <artifactId>jetspeed-mvn-maven-plugin</artifactId>
+  <version>${org.apache.portals.jetspeed.version}</version>
+  <configuration>
+
+    <targets combine.children="append">
+      ...
+      <target>
+        <id>...</id>
+        <depends>...</depends>
+        <name>...</name>
+        <dir>...</dir>
+        <goals>...</goals>
+        <profiles>...</profiles>
+        <properties>
+          ...
+        </properties>
+        <settingsFile>...</settingsFile>
+        <mavenOpts>...</mavenOpts>
+      </target>
+      ...
+    </targets>
+    <defaultTarget>...</defaultTarget>
+    <useSettings>...</useSettings>
+    <properties>
+      ...
+    </properties>
+    <mavenOpts>...</mavenOpts>
+
+  </configuration>
+</plugin>]]></source>
+        </p>
+    </section>
+    <section name="Default plugin configuration">
+      <p>
+        As can be seen from the above configuration overview, the primary configuration element is the list of targets and the target elements themselves.
+      </p>
+      <subsection name="&lt;targets combine.children=&quot;append&quot;&gt;">
+        <p>
+          One important and <strong>essential</strong> part of the configuration is the <strong><code>combine.children="append"</code></strong> attribute specified
+          for the <strong><code>targets</code></strong> element.
+        </p>
+        <p>
+          Maven 2 plugin configuration parsing (using Xpp3) by default <strong><em>merges</em></strong> configuration elements for children elements if not defined!
+          This default behavior allows to only define <strong>overriding</strong> properties for a certain configuration element.
+        </p>
+        <p>
+          But, for the target configurations this is <strong><em>not</em></strong> very convenient because it requires to specify <strong><em>all</em></strong> optional properties for
+          a <strong><code>task</code></strong> element to prevent "merging in" property values from <em>unrelated</em> previously defined target elements.
+        </p>
+        <p>
+          To solve this inconvenience, a <strong><code>combine.children="append"</code></strong> attribute can be specified on a parent element to use <strong><em>append</em></strong>
+          instead of <strong><em>merge</em></strong> when parsing the child elements.
+        </p>
+        <p>
+          So, make sure to always use <strong><code>&lt;targets combine.children="append"&gt;</code></strong> to ensure a target configuration is actually parsed as specified!
+        </p>
+      </subsection>      
+      <subsection name="General options"> 
+        <p>
+          Besides the targets, a few additional (all optional) configuration elements can be specified: 
+        </p>
+        <table>
+          <tr>
+            <th>Element</th>
+            <th width="90%">Description</th>
+          </tr>
+          <tr>
+            <td>defaultTarget</td>
+            <td>
+                The intended usage of the jetspeed:mvn is to specify a target on the commandline using <strong><code>$mvn jetspeed:mvn -Dtarget=&lt;target id&gt;</code></strong>.<br/>                
+                If there is a real need for a default (and thereby very common) target, its <strong>id</strong> property can be specified here which will then be
+                used if no commandline parameter is specified.
+            </td>
+          </tr>
+          <tr>
+            <td>useSettings</td>
+            <td>
+              <code>default: true</code><br/>
+              The optional usage of custom Maven settings for the execution of a specific target will be explained further below, but this setting determines the default
+              lookup and usage of a <strong><code>jetspeed-mvn-settings.xml</code></strong> file if for a target no specific <strong><code>settingsFile</code></strong> itself is configured. 
+            </td>
+          </tr>
+          <tr>
+            <td>properties</td>
+            <td>
+              The usage of runtime properties provided to the Maven execution environment of a specific target will be explained further below,
+              but <strong>global</strong> properties (which can be overridden) to be used for all targets can be configured here.<br/>
+              The format for definining properties is the same as used for standard Maven project properties:<br/>
+              <pre>
+                &lt;property-name&gt;value&lt;/property-name&gt;</pre>
+            </td>
+          </tr>
+          <tr>
+            <td>mavenOpts</td>
+            <td>
+              <code>default: none</code><br/>
+              Default Maven runtime options to be set for a target execution environment can be specified here. For a specific target these can be overrridden with its
+              own <strong><code>mavenOpts</code></strong> configuration. 
+            </td>
+          </tr>
+        </table>
+      </subsection>
+    </section>
+    <section name="Target configuration">
+      <p>
+        The execution of a target in a separate Maven environment requires three different sets of parameters:
+        <ul>
+          <li>the target itself and the possible other targets it depends on</li>
+          <li>the (custom) Maven project file to be invoked</li>         
+          <li>the goals, profiles, settings and runtime properties to be used</li>         
+        </ul> 
+      </p>
+      <subsection name="target identification and its dependencies">
+        <p>
+          A target is uniquely identified (within the scope of the current project) by its required <strong><code>&lt;id/&gt;</code></strong> element:
+        <source><![CDATA[<target>
+  <id>aTarget</id>
+  ...
+</target>]]></source>
+        </p>
+        <p>
+          Optionally, dependencies on other targets can be specified with a <strong><code>&lt;depends/&gt;</code></strong> element using a comma separated list of other target
+          <strong><code>id</code></strong> values:
+        <source><![CDATA[<target>
+  <id>target1</id>
+  <depends/>
+  ...
+</target>
+<target>
+  <id>target2</id>
+  <depends>target1</depends>
+  ...
+</target>
+<target>
+  <id>target3</id>
+  <depends>target1,target2</depends>
+  ...
+</target>]]></source>
+        </p>        
+        <p>
+          The above example specifies that <strong><code>target2</code></strong> depends on <strong><code>target1</code></strong> and <strong><code>target3</code></strong> depends on both
+          <strong><code>target1</code></strong> and <strong><code>target2</code></strong>. 
+        </p>
+        <p>
+          This indicates that when <strong><code>target3</code></strong> is to be executed, <strong><code>target1</code></strong> and <strong><code>target2</code></strong> need to be executed first (and
+          in that order).
+        </p>
+        <p>
+          When a target dependency chain is resolved, the dependencies will be invoked <em>in order</em> as defined, whereby a single target will <em>only</em> be executed
+          <em>once</em>, even if multiple dependent targets define a dependency on the same other target.
+        </p>
+        <p>
+          With the above example, the actual execution order thus will be: <strong><code>target1,target2,target3</code></strong>,
+          <em>not</em>: <strong><code>target1,target1,target2,target3</code></strong> 
+        </p>
+        <p>
+          This means that for the above example <strong><code>target3</code></strong> actually can be defined even simpler as <strong><code>target2</code></strong> already depends
+          on <strong><code>target1</code></strong>:
+        <source><![CDATA[<target>
+  <id>target3</id>
+  <depends>target2</depends>
+  ...
+</target>]]></source>
+        </p>
+      </subsection>
+      <subsection name="target Maven project file">
+        <p>
+          Which (custom) Maven project file is to be invoked for a target is determined from the (both optional) <strong><code>name</code></strong> and <strong><code>dir</code></strong>
+          elements:
+        <source><![CDATA[<target>
+  <id>dbInit</id>
+  <name>db</name>
+  <dir>@rootdir@/my-portal</dir>
+  ...
+</target>]]></source>
+        </p>
+        <p>
+          The <strong><code>name</code></strong> element is used to resolve a <em>custom</em> Maven project file named: jetspeed-mvn-<strong>${name}</strong>-pom.xml.
+        </p>
+        <p>
+          The <strong><code>dir</code></strong> element is used to resolve the location of the determined target Maven project file.
+        </p>
+        <h4>name and dir not defined</h4>
+        <p>
+          If both <strong><code>name</code></strong> and <strong><code>dir</code></strong> are not defined, jetspeed:mvn will do nothing for <em>this</em> target, but <em>will</em> execute
+          the targets which it <strong><code>depends</code></strong> on, e.g. executing:
+        <source>$mvn jetspeed:mvn -Dtarget=target3</source> using the following configuration:
+        <source><![CDATA[<target>
+  <id>target1</id>
+  <depends/>
+  <name>pomA</name>
+  ...
+</target>
+<target>
+  <id>target2</id>
+  <depends>target1</depends>
+  <name>pomB</name>
+  ...
+</target>
+<target>
+  <id>target3</id>
+  <depends>target2</depends>
+</target>]]></source>
+          will still result in <strong><code>pomA</code></strong> and <strong><code>pomB</code></strong> to be invoked.
+        </p>
+        <h4>only dir defined</h4>
+        <p>
+          If only <strong><code>dir</code></strong> is defined, jetspeed:mvn will lookup the standard Maven pom.xml in the specified directory.
+        </p>
+        <p>
+          The file lookup is done relative to the current working directory, e.g. the Maven project in which jetspeed:mvn is invoked.  
+        </p>
+        <p>
+          Alternatively, an absolute directory can be specified too, or the special @rootdir@ variable can be used (see below).
+        </p>
+        <p>
+          <em>Hint: to invoke the default Maven pom.xml in the current directory, specify &lt;dir&gt;./&lt;/dir&gt;</em>.
+        </p>
+        <h4>only name defined</h4>
+        <p>
+          If only <strong><code>name</code></strong> is defined, jetspeed:mvn will look for a custom Maven project file named jetspeed-mvn-<strong>${name}</strong>-pom.xml
+          first in the <em>current</em> Maven project directory, and if not found search for it upwards in the parent project(s) of the current Maven project.
+        </p>
+        <h4>both name and dir defined</h4>
+        <p>
+          When both <strong><code>name</code></strong> and <strong><code>dir</code></strong> are defined, the custom Maven project file named
+          jetspeed-mvn-<strong>${name}</strong>-pom.xml has to exist in the specified <strong><code>dir</code></strong>.
+        </p>
+        <h4>@rootdir@</h4>
+          <p>
+            The special variable <strong><code>@rootdir@</code></strong> can be used to refer to the (absolute) path of the topmost Maven project of the current project.             
+          </p>
+          <p>
+            If however a property <strong>rootdir<code></code></strong> already is defined for the current Maven project (or in one of its parent projects), its value will
+            be used instead.
+          </p>
+          <h4>execution working directory</h4>
+          <p>
+            Important to note is that <em>before</em> the resolved (custom) Maven project file is invoked, the current working directory will be (temporarily) changed
+            to the directory containing the project file. So all relative file and resource references will be resolved relative to this directory as well! 
+          </p>
+      </subsection>
+      <subsection name="target execution parameters and environment">
+        <p>
+          Once a target its target Maven project file is determined, its execution environment and runtime parameters are determined based on the following (all optional) elements
+          and the default/global elements defined for all targets (see above):
+        <source><![CDATA[<target>
+  <id>aTarget</id>
+  <name>db</name>
+  <dir>@rootdir@</dir>
+  
+  <goals>process-resources</goals>
+  <profiles>proddb</profiles>
+  <properties>
+    <!-- (default) production target specific properties -->
+  </properties>
+  <settingsFile>@rootdir@/prod-settings.xml</settingsFile>
+  <mavenOpts>-Xms128m -Xmx256m</mavenOpts>
+
+</target>]]></source>
+        </p>
+        <h4>goals</h4>
+        <p>
+          The (custom) target Maven project file can be invoked to run or or more goals using one or more profiles and even a specific Maven settings file. 
+        </p>
+        <p>
+          The <strong><code>goals</code></strong> element can optionally be defined to specify a comma separated list of goals to run:
+          <source>&lt;goals&gt;goal1,goal2,goal3&lt;/goals&gt;</source>.
+          If the <strong><code>goals</code></strong> element is not defined, the target Maven project file must have a <strong><code>defaultGoal</code></strong> build element:
+        <source><![CDATA[<build>
+  <defaultGoal>process-resources</defaultGoal>
+</build>]]></source>
+        </p>
+        <h4>profiles</h4>
+        <p>
+          Like with goals, optionally one or more profiles to be used (by all the goals to be run) can be specified as comma separated list:
+          <source>&lt;profiles&gt;profile1,profile2,profile3&lt;/profiles&gt;</source>
+        </p>
+        <h4>properties</h4>
+        <p>
+          A very important requirement for the execution of a target is providing the Maven execution environment with the right set of runtime parameters. 
+        </p>
+        <p>
+          The jetspeed:mvn plugin will accumulate the set of properties to be provided as runtime (e.g. -D) parameters <em>for each target execution individually</em>
+          in the following order:
+          <table>
+            <tr>
+              <th>Order</th>
+              <th>Source</th>
+              <th width="90%">Lookup</th>
+            </tr>
+            <tr>
+              <td>1</td>
+              <td><span style="whitespace:nowrap"><![CDATA[<configuration><properties/></configuration]]></span></td>
+              <td>the jetspeed:mvn default configuration properties</td>
+            </tr>
+            <tr>
+              <td>2</td>
+              <td><span style="whitespace:nowrap"><![CDATA[<target><properties/></target>]]></span></td>
+              <td>the target specific properties</td>
+            </tr>
+            <tr>
+              <td>3</td>
+              <td><span style="whitespace:nowrap">current Maven project properties</span></td>
+              <td>Note: this includes properties defined in the parent project(s) of the current project and even the default Maven settings</td>
+            </tr>
+            <tr>
+              <td>4</td>
+              <td><span style="whitespace:nowrap">jetspeed-mvn.properties</span></td>
+              <td>
+                This file is searched for in the current Maven project directory or else upwards in its parent project(s) directory.<br/>
+                The properties file found will be <em><strong>interpolated</strong></em> with the already resolved properties using ${} variable replacements.                
+              </td>
+            </tr>
+            <tr>
+              <td>5</td>
+              <td><span style="whitespace:nowrap">jetspeed-mvn-${target name}.properties</span></td>
+              <td>
+                This file is searched for in the current Maven project directory or else upwards in its parent project(s) directory.<br/>
+                The properties file found will be <em><strong>interpolated</strong></em> with the already resolved properties using ${} variable replacements.                
+              </td>
+            </tr>
+            <tr>
+              <td>6</td>
+              <td><span style="white-space:nowrap">jetspeed-mvn-${target name}-${target id}.properties</span></td>
+              <td>
+                This file is searched for in the current Maven project directory or else upwards in its parent project(s) directory.<br/>
+                The properties file found will be <em><strong>interpolated</strong></em> with the already resolved properties using ${} variable replacements.                
+              </td>
+            </tr>
+          </table> 
+        </p>
+        <p>
+          The jetspeed:mvn specific property files are <em>individually</em> looked up, e.g. the location of one doesn't depict the location of another.
+        </p>
+        <p>
+          <em>
+            Warning: be careful depending on properties resolved from the current Maven project as these might be different
+            depending on from which project folder the jetspeed:mvn is invoked.<br/>
+          </em>
+        </p>
+        <h4>useSettings and settingsFile</h4>
+        <p>
+          Certain Maven configuration elements and properties can or should only be specified in a <a href="http://maven.apache.org/settings.html">Maven settings</a> file,
+          like security sensitive server parameters (username, password etc.).
+        </p>
+        <p>
+          While Maven will by default lookup the settings.xml file from the user's home directory: <code><strong>${user.home}/.m2/settings.xml</strong></code>, this
+          isn't always very inconvenient, especially not if one is involved in many different projects each with its own specific settings requirements. 
+        </p>
+        <p>
+          Sometimes it is more convenient or even required to maintain project specific settings with or within the project source (control) environment itself.
+        </p>
+        <p>
+          The jetspeed:mvn plugin can use a custom setttings file (by default) which is controlled by the optional configuration <strong><code>useSettings</code></strong> element,
+          a target specific <strong><code>settingsFile</code></strong> element or a specific property <strong><code>jetspeed.mvn.settings.xml</code></strong>.
+        </p>
+        <p>
+          When the jetspeed:mvn configuration element &lt;useSettings&gt;true&lt;/useSettings&gt; is specified (which it is by default), 
+          jetspeed:mvn will look for a custom Maven settings file named jetspeed-mvn-settings.xml first in the <em>current</em> Maven project directory, and if not found search
+          for it upwards in the parent project(s) of the current Maven project.
+        </p>
+        <p>
+          Alternatively, a target <strong><code>settingsFile</code></strong> element can be used to use a target specific settings file, as shown in the full example
+          target configuration above.
+        </p>
+        <p>
+          Finally, a (target specific) settings file can also be defined as property either for the current Maven project or one of its parents, or in the
+          resolved target specific properties (which do incorparate the current Maven project properties) using the property name: <strong><code>jetspeed.mvn.settings.xml</code></strong>.
+        </p>
+        <p>
+          A custom Maven settings file specified as <strong><code>jetspeed.mvn.settings.xml</code></strong> property overrules a target specific <strong><code>settingsFile</code></strong>,
+          and these both overrule a jetspeed:mvn default <strong><code>useSettings</code></strong> configuration and lookup. 
+        </p>
+        <h4>Advanced: Maven project and settings file variables interpolation</h4>
+        <p>
+          An advanced feature to even further configuring the target Maven project and/or settings file is inherited from the
+          <a href="http://maven.apache.org/plugins/maven-invoker-plugin/advance-usage.html">Maven Invoker Plugin</a> from which the jetspeed:mvn plugin was derived.
+        </p>
+        <p>
+          Before the resolved Maven project and optional settings file are actually executed and used, an <em>interpolated</em> version of these files are temporarily written
+          to disk in which variables between <strong><code>@</code></strong> markers are filtered using the resolved target properties (see above).
+        </p>
+        <p>
+          The Jetspeed-2 Portal project itself uses this feature in its jetspeed-mvn-db-init-pom.xml for initializing either a test or production
+          database.
+        </p>
+        <p>  
+          The actually database configuration properties used by Jetspeed have a common prefix: either <strong><code>org.apache.jetspeed.test.database</code></strong>
+          or <strong><code>org.apache.jetspeed.production.database</code></strong>.
+        </p>
+        <p>
+          For the initialization of the two different target (test|production) databases, the jetspeed-mvn-db-init-pom.xml references these configuration parameters using the
+          following prefix: <strong><code>org.apache.jetspeed.@database.type@.database</code></strong>:
+        <source><![CDATA[<plugin>
+  <groupId>${pom.groupId}</groupId>
+  <artifactId>jetspeed-db-maven-plugin</artifactId>
+  <version>${pom.version}</version>
+  <configuration>
+    <connection>
+      <username>${org.apache.jetspeed.@database.type@.database.user}</username>
+      <password>${org.apache.jetspeed.@database.type@.database.password}</password>
+      <url>${org.apache.jetspeed.@database.type@.database.url}</url>
+      <driver>${org.apache.jetspeed.@database.type@.database.driver}</driver>
+    </connection>
+  </configuration>
+  ...]]></source>
+          The separate jetspeed-mvn targets used for the initialization each define a different value for property <strong><code>database.type</code></strong>:
+        <source><![CDATA[<target>
+  <id>testdb</id>
+  <name>db-init</name>
+  <properties>
+    <database.type>test</database.type>
+  </properties>
+</target>
+<target>
+  <id>proddb</id>
+  <name>db-init</name>
+  <properties>
+    <database.type>production</database.type>
+  </properties>
+</target>]]></source>
+          As result of the automatic interpolation of the target project (and settings) file, only a single definition for the jetspeed-db:init plugin is needed
+          handling both initializing test and production databases.
+        </p>
+        <p>
+          This feature also makes it very easy to later add even more target databases, like for staging purposes: just add another target with value "staging" for
+          the database.type property (and of course provide the corresponding org.apache.jetspeed.staging.database.* properties in the jetspeed-mvn-settings.xml).
+        </p>
+        <h4>mavenOpts</h4>
+        <p>
+          Finally, the special overriding Maven MAVEN_OPTS environment variable can also be specified for a specific target using a <strong><code>mavenOpts</code></strong> element,
+          or if not defined, also a default for all targets as jetspeed:mvn configuration element (see above).
+        </p>
+      </subsection>
+      <subsection name="target configuration summary">
+        <p>
+          The following table summarizes the configuration elements for a target:  
+        </p>
+        <table>
+          <tr>
+            <th>Element</th>
+            <th width="90%">Description</th>
+          </tr>
+          <tr>
+            <td>id</td>
+            <td>
+              The only required element to uniquely identify a target.<br/>
+            </td>
+          </tr>
+          <tr>
+            <td>depends</td>
+            <td>
+              The optional comma separated list of other target ids this target depends upon and which will be automatically executed beforehand
+            </td>
+          </tr>
+          <tr>
+            <td>name</td>
+            <td>
+              The optional name of the target which is used to lookup a <em>custom</em> Maven project file named: jetspeed-mvn-${name}-pom.xml.<br/>
+              If only element <strong><code>dir</code></strong> is defined, the standard Maven pom.xml project file from the <strong><code>dir</code></strong>
+              will be used.              
+            </td>
+          </tr>
+          <tr>
+            <td>dir</td>
+            <td>
+              The optional directory where to lookup a custom Maven project file (using the <strong><code>name</code></strong>) of the target.<br/>
+              If <strong><code>name</code></strong> is not defined the standard Maven pom.xml project file will be used from this directory.
+            </td>
+          </tr>
+          <tr>
+            <td>goals</td>
+            <td>
+              The optional comma separated list of Maven goals to be invoked on the resolved (custom) Maven project file.<br/>
+              If not defined, the target Maven project file must have a <strong><code>&lt;defaultGoal/&gt;</code></strong> build element configured.              
+            </td>
+          </tr>
+          <tr>
+            <td>profiles</td>
+            <td>
+              The optional comma separated list of profiles to be provided when the resolved (custom) Maven project file is executed.
+            </td>
+          </tr>
+          <tr>
+            <td>properties</td>
+            <td>
+              The optional target specific properties to be provided as runtime (-D) parameters.<br/>
+              These properties can be overruled by jetspeed:mvn specific property files, see previous section.
+            </td>
+          </tr>
+          <tr>
+            <td>settingsFile</td>
+            <td>
+              The location of an optional custom Maven settings file to be used when executing this target.<br/>
+              If not defined, the default &lt;useSettings/&gt; configuration element value (true by default) determines if a jetspeed-mvn-settings.xml file
+              is looked up instead.
+              Note: This settingsFile can also be overruled with a property <strong><code>jetspeed.mvn.settings.xml</code></strong>, see previous section. 
+            </td>
+          </tr>
+          <tr>
+            <td>mavenOpts</td>
+            <td>
+              The optional value for the special Maven MAVEN_OPTS Maven environment variable to be used.<br/>
+              If not defined, the (also optional) default &lt;mavenOpts/&gt; configuration element value will be used.
+            </td>
+          </tr>
+        </table>
+      </subsection> 
+    </section>
+    <section name="Usage">
+      <p>
+        Finally, actually using the jetspeed:mvn plugin and invoking a specific target will be very simple:
+        <source><![CDATA[$mvn jetspeed:mvn -Dtarget=<target id>]]></source>
+      </p>
+      <p>
+        Optionally, if also a <strong><code>defaultTarget</code></strong> is configured for the jetspeed:mvn plugin, even the following will work:
+        <source><![CDATA[$mvn jetspeed:mvn]]></source>
+        but usually more than one target will be needed for a specific (Jetspeed Portal) project in which case defining and using a
+        <strong><code>defaultTarget</code></strong> is not really recommended. 
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-mvn-plugin.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-mvn-plugin.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-portal-resources.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-portal-resources.xml?rev=678019&view=auto
==============================================================================
--- portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-portal-resources.xml (added)
+++ portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-portal-resources.xml Fri Jul 18 12:57:49 2008
@@ -0,0 +1,57 @@
+<?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.
+
+  $Id$
+-->
+<document>
+  <properties>
+    <title>The jetspeed-portal-resources artifact</title>
+    <authors>
+      <person name="Ate Douma" email="ate@douma.nu" />
+    </authors>
+  </properties>
+  <body>
+    <section name="The jetspeed-portal-resources artifact">
+      <p>
+        The Jetspeed-2 Portal, <em>as a portal framework</em>, provides many optional features and configuration elements, some of which are used even during the build (and testing)
+        of the Jetspeed-2 Portal project itself.
+      </p>
+      <p>
+        Additionally, because of the highly customizable configuration of a Jetspeed-2 Portal, not all of its available resources and configuration files are needed nor desired
+        to be used and packaged for each and every target environment.  
+      </p>
+      <p>
+        For these reasons, the Jetspeed-2 Portal project provides pre-packaged resources as Maven Artifact, the <strong><code>jetspeed-portal-resources:jar</code></strong>,
+        which can be used to only selectively use the needed resources for a specific target (artifact) or integration task.
+      </p>
+      <p>
+        Important and commonly used resources provided by the jetspeed-portal-resources artifact are for example:
+        <ul>
+          <li>Spring configurations (/assembly)</li>
+          <li>Database schema definitions (/ddl-schema)</li>
+          <li>Pre-generated database ddl scripts (/ddl)</li>
+          <li>Portal and application server property and configurations files (/conf)</li>
+          <li>Predefined minimal and example database initialization data (/seed)</li>
+        </ul>
+      </p>
+      <p>
+        Both the <a href="jetspeed-unpack-plugin.html">jetspeed-unpack:unpack</a> and <a href="jetspeed-db-init-plugin.html">jetspeed-db:init</a> plugin can unpack selected resources
+        from resource archives for which commonly the jetspeed-portal-resources artifact is used.
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-portal-resources.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/trunk/maven/src/site/xdoc/jetspeed-portal-resources.xml
------------------------------------------------------------------------------
    svn:keywords = Id



---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message