Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/index.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/index.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/index.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/index.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,122 @@ +<?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: index.xml 779028 2009-05-27 06:38:26Z ate $ +--> +<document> + <properties> + <title>Building and developing Jetspeed-2 using Maven-2</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Building and developing Jetspeed-2 using Maven-2"> + <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 as well as a portal framework 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 the Jetspeed-2 Portal is that it can be adapted and configured for very divers and specific requirements. To be able to <em>leverage</em> + these features for custom portal projects, configuring Jetspeed-2 to assemble and integrate it for many different 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> it. + </p> + <p> + Setting up and interacting with back-end databases, creating and maintaining multiple portal configurations for a specific target deployment environments, 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 such complex integration requirements (from a Jetspeed-2 project POV) and still leverage the Maven 2 toolset, a few custom + Maven "plugins" have been written to provide 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 for each of these Maven plugins is provided through the <a href="jetspeed-maven-plugins.html">Plugins Overview</a> + of the <em>Plugins</em> menu and the corresponding plugin pages. + </p> + <p> + How to build Jetspeed-2 from source, using these plugins, is provided on the <a href="maven-2-build.html">From Source</a> page + on the <em>Building Jetspeed</em> menu. + </p> + </subsection> + <subsection name="Quickstart a new Custom Portal Project using the Jetspeed Archetype"> + <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-layout.html">project layout and configuration</a> however will be in most cases the same. + </p> + <p> + A quick and easy way of setting up an initial build project configuration is using the <em>Jetspeed Archetype</em> Maven plugin + for which detailed description and usage is provided on the <a href="jetspeed-archetype.html">Jetspeed Archetype</a> page of + the <em>Building Jetspeed</em> menu. + </p> + </subsection> + <subsection name="PREREQUISITE: configuration of the Maven Settings pluginGroups"> + <p> + Using a non-standard Maven Plugin (e.g. not provided by the Maven or CodeHaus Plugin projects themselves) from the command line requires a fully qualified + specification of the plugin coordinates and goal to execute. This requires in most cases a cumbersome, error prone and verbose amount of typing! + </p> + <p> + For the Jetspeed-2 Maven Plugins for example, invoking the <a href="jetspeed-maven-plugins.html">jetspeed:mvn</a> plugin then requires something like the following: + <source>$mvn org.apache.portals.jetspeed-2:jetspeed:mvn -Dtarget=demo</source> + </p> + <p> + This can be simplified however by configuring in your user Maven settings how to resolve (additional) plugin groups automatically without having to specify + the full plugin groupId coordinate 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 user Maven settings.xml is therefore recommended and assumed by all example usages given + throughout the Jetspeed-2 documentation. + </p> + <p> + The 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 <em><code>org.apache.portals.jetspeed-2</code></em> needs to be added as a pluginGroup definition within your user 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> + When the Jetspeed-2 pluginGroup is defined, the example commandline execution as shown above can be simplified to: + <source>$mvn jetspeed:mvn -Dtarget=demo</source> + </p> + </subsection> + </section> + </body> +</document> \ No newline at end of file
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-archetype.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-archetype.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-archetype.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-archetype.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,344 @@ +<?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: jetspeed-archetype.xml 1174924 2011-09-23 17:58:04Z woonsan $ +--> +<document> + <properties> + <title>Quickstart a new custom Jetspeed Portal project using the jetspeed-archetype Maven Plugin</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + <person name="Woonsan Ko" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Quickstart a new custom Jetspeed Portal project using the jetspeed-archetype Maven Plugin"> + <p> + Jetspeed-2.2 provides an archetype Maven plugin to allow portal developers to create custom portal projects very easily. When starting a new Jetspeed-based portal project, we strongly recommend that you create a custom portal project by the jetspeed-archetype Maven Plugin, and do not edit the Jetspeed-2 source and resources directly. + </p> + <p> + This document will guide you how to run the command and the steps to create a sample portal named <strong>hello</strong>. + </p> + <p>You need the following prerequisites: + <ul> + <li>Java Development Kit 1.5</li> + <li><a class="externalLink" href="http://maven.apache.org/";>Apache Maven</a> 2.2.1 or higher</li> + <li><a class="externalLink" href="http://tomcat.apache.org/";>Apache Tomcat</a> 6.0.33 or higher</li> + </ul> + </p> + <subsection name="Optional: Building and Installing Jetspeed-2 Maven Plugins"> + <p> + Because Jetspeed Maven Plugins and Archetype Plugins will be automatically downloaded by Maven-2, you don't need to build and install those from the Jetspeed-2 source. + </p> + <p><em>Note</em>: you may skip this section for simplicity in normal cases.</p> + <p> + However, if you want this for some reasons, you can build and install the Jetspeed-2 Maven Plugins and Archetype Plugins from the source of Jetspeed-2 with the following command in the root directory of Jetspeed-2 source: + <div class="source"><pre>$mvn install -P init</pre> + </div> + </p> + <p> + 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="Using the jetspeed-archetype Maven Plugin"> + <p> + To use jetspeed-archetype Maven Plugin, you can run a command like the following: + <div class="source"><code><pre>mvn org.apache.maven.plugins:maven-archetype-plugin:2.0-alpha-4:generate \ + -DarchetypeGroupId=org.apache.portals.jetspeed-2 \ + -DarchetypeArtifactId=jetspeed-archetype \ + -DarchetypeVersion=2.2.1 \ + -DartifactId=hello \ + -Dpackage=org.example \ + -DgroupId=org.example -Dversion=1.0.0</pre></code></div> + </p> + <p>In the above command, the variables, "artifactId", "package" and "groupId", are project-specific ones. So you should provide variables for your project.</p> + <p>By the way, the other variables in the above command are from the Maven Archetype Plugin Specification. Please refer to <a href="http://maven.apache.org/plugins/maven-archetype-plugin/";>Maven Archetype Plugin</a> homepage for details.</p> + </subsection> + <subsection name="Generating Hello Portal Application Example"> + <p> + To build a custom portal project named 'hello', you may need to move to a folder under which your project folder should be located. For example, + <div class="source"><code><pre>$ cd ~/projects +$ mvn org.apache.maven.plugins:maven-archetype-plugin:2.0-alpha-4:generate \ +-DarchetypeGroupId=org.apache.portals.jetspeed-2 \ +-DarchetypeArtifactId=jetspeed-archetype \ +-DarchetypeVersion=2.2.1 \ +-DartifactId=hello \ +-Dpackage=org.example \ +-DgroupId=org.example -Dversion=1.0.0 + </pre></code></div> + </p> + <p> + <em>Note: </em>After running the above command, you will meet a prompt for confirmation. By pressing enter key it will continue to generate a custom portal project. + </p> + <p>With the above command, the <strong>jetspeed-archetype</strong> generates a complete Maven-2 project directory structure for developing a custom portal as well as portlet applications. Here is an overview of directories created by the jetspeed-archetype (directories are relative to the custom portal root):</p> + <table> + <thead> + <tr> + <th>Directory</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>hello</td> + <td>Project root directory</td> + </tr> + <tr> + <td>hello/hello-portal</td> + <td>Custom portal web application root directory</td> + </tr> + <tr> + <td>hello/hello-portal/src</td> + <td>Source directory for custom portal</td> + </tr> + <tr> + <td>hello/hello-portal/src/main/webapp/WEB-INF/pages</td> + <td>Source directory for custom PSML page sources</td> + </tr> + <tr> + <td>hello/hello-portal/src/sql/min</td> + <td>Source directory for seeding initial database</td> + </tr> + <tr> + <td>hello/hello-pa</td> + <td>Custom portlet application root directory</td> + </tr> + <tr> + <td>hello/hello-pa/src</td> + <td>Source directory for custom portlet application</td> + </tr> + </tbody> + </table> + </subsection> + <subsection name="Building Hello Portal Application Example"> + <p> + To configure the generated portal project, you need to edit <strong><code>jetspeed-mvn-settings.xml</code></strong> file in the project root directory and change the following: + <table> + <thead> + <tr> + <th>Property</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>org.apache.jetspeed.server.home</td> + <td>The Tomcat server directory which is the target of the custom portal deployment.</td> + </tr> + <tr> + <td>org.apache.jetspeed.catalina.version.major</td> + <td>The major version number of Tomcat. Supported values are 6 and 7. Default value is 6.</td> + </tr> + <tr> + <td>org.apache.jetspeed.production.jdbc.driver.groupId</td> + <td>The groupdId of your JDBC driver. For example, this can be "org.apache.derby" for Apache Derby JDBC driver.</td> + </tr> + <tr> + <td>org.apache.jetspeed.production.jdbc.driver.artifactId</td> + <td>The artifactId of your JDBC driver. For example, this can be "derby" for Apache Derby JDBC driver.</td> + </tr> + <tr> + <td>org.apache.jetspeed.production.jdbc.driver.version</td> + <td>The version of your JDBC driver.</td> + </tr> + <tr> + <td>org.apache.jetspeed.production.database.default.name</td> + <td> + The database name which is used by DDLUtils to generate database schema SQL scripts for your specific database. + Depending on your database platform, this must be one of the followings: "db2", "db2v8", "derby", "mssql", "mysql", "mysql5", "oracle9", "oracle10", "postgresql", "sapdb" and more. (For details about support for databases, you can refer to <a href="http://db.apache.org/ddlutils/";>Apache DB Project - DdlUtils Homepage</a>.) + </td> + </tr> + <tr> + <td>org.apache.jetspeed.production.database.url</td> + <td>The JDBC URL for your database access.</td> + </tr> + <tr> + <td>org.apache.jetspeed.production.database.driver</td> + <td>The JDBC driver class name for your database access.</td> + </tr> + <tr> + <td>org.apache.jetspeed.production.database.user</td> + <td>The database user name for your database access.</td> + </tr> + <tr> + <td>org.apache.jetspeed.production.database.password</td> + <td>The database user password for your database access.</td> + </tr> + </tbody> + </table> + </p> + <p> + Initially, the <strong>jetspeed-archetype</strong> generates a <strong><code>jetspeed-mvn-settings.xml</code></strong> to use Apache Derby like the following example: + <div class="source"><code><pre><![CDATA[<settings xmlns="http://maven.apache.org/POM/4.0.0";> + <profiles> + <profile> + + ... + + <properties> + <org.apache.jetspeed.server.home>/change/this/apache-tomcat-6.0.33/</org.apache.jetspeed.server.home> + <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major> + <org.apache.jetspeed.production.jdbc.driver.groupId>org.apache.derby</org.apache.jetspeed.production.jdbc.driver.groupId> + <org.apache.jetspeed.production.jdbc.driver.artifactId>derby</org.apache.jetspeed.production.jdbc.driver.artifactId> + <org.apache.jetspeed.production.jdbc.driver.version>10.3.2.1</org.apache.jetspeed.production.jdbc.driver.version> + <org.apache.jetspeed.production.database.default.name>derby</org.apache.jetspeed.production.database.default.name> + <org.apache.jetspeed.production.database.url>jdbc:derby:/tmp/jetspeed/derby/productiondb;create=true</org.apache.jetspeed.production.database.url> + <org.apache.jetspeed.production.database.driver>org.apache.derby.jdbc.EmbeddedDriver</org.apache.jetspeed.production.database.driver> + <org.apache.jetspeed.production.database.user></org.apache.jetspeed.production.database.user> + <org.apache.jetspeed.production.database.password></org.apache.jetspeed.production.database.password> + </properties> + </profile> + </profiles> +</settings> + ]]></pre></code></div> + </p> + <p> + So, if you want to deploy your custom portal to other Tomcat location and to use other database, you should change the "org.apache.jetspeed.server.home" property and the other database-related properties. For example, the following shows one usage with MySQL database: + <div class="source"><code><pre><![CDATA[<settings xmlns="http://maven.apache.org/POM/4.0.0";> + <profiles> + <profile> + + ... + + <properties> + <org.apache.jetspeed.server.home>C:/apache-tomcat-6.0.33/</org.apache.jetspeed.server.home> + <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major> + <org.apache.jetspeed.production.jdbc.driver.groupId>mysql</org.apache.jetspeed.production.jdbc.driver.groupId> + <org.apache.jetspeed.production.jdbc.driver.artifactId>mysql-connector-java</org.apache.jetspeed.production.jdbc.driver.artifactId> + <org.apache.jetspeed.production.jdbc.driver.version>5.1.6</org.apache.jetspeed.production.jdbc.driver.version> + <org.apache.jetspeed.production.database.default.name>mysql5</org.apache.jetspeed.production.database.default.name> + <org.apache.jetspeed.production.database.url>jdbc:mysql://127.0.0.1/jetspeed?useServerPrepStmts=false&jdbcCompliantTruncation=false</org.apache.jetspeed.production.database.url> + <org.apache.jetspeed.production.database.driver>com.mysql.jdbc.Driver</org.apache.jetspeed.production.database.driver> + <org.apache.jetspeed.production.database.user>username</org.apache.jetspeed.production.database.user> + <org.apache.jetspeed.production.database.password>password</org.apache.jetspeed.production.database.password> + </properties> + </profile> + </profiles> +</settings> + ]]></pre></code></div> + </p> + <p> + You can build and deploy your custom portal to your Tomcat installation by using the following command: + <div class="source"><pre>$mvn org.apache.portals.jetspeed-2:jetspeed-mvn-maven-plugin:mvn -Dtarget=all</pre> + </div> + You can shorten the above command by adding the Jetspeed Maven Plugin's groupId to the list of groupIds searched by default. + To do this, you need to add the following to your ${user.home}/.m2/settings.xml file: + <div class="source"><pre><settings xmlns="http://maven.apache.org/POM/4.0.0"> +<pluginGroups> +<!-- add the following line to shorten the command invoking the Jetspeed Maven Plugin. --> +<pluginGroup>org.apache.portals.jetspeed-2</pluginGroup> +</pluginGroups> +</settings></pre></div> + Now you can use a shorter command like the following: + <div class="source"><pre>$mvn jetspeed:mvn -Dtarget=all</pre> + </div> + </p> + <p> + Start your Tomcat:<br/> + Note that the setting of CATALINA_OPTS is optional in the following examples. (See <a href="#Note_on_Permanent_Generation_Size_of_Your_JVM">Note on Permanent Generation Size of Your JVM</a> for detail.) + <div class="source"><pre> +$ cd $TOMCAT_HOME/bin +$ export CATALINA_OPTS="-Xmx256m -XX:MaxPermSize=128m" +$ ./catalina.sh run + </pre></div> + </p> + <p> + Use your custom portal: + <a class="externalLink" href="http://localhost:8080/hello";>http://localhost:8080/hello</a> + </p> + </subsection> + <subsection name="Note on Permanent Generation Size of Your JVM"> + <p> + <em>Note:</em> You may need to increase the permanent generation size of your JVM when there are a lot of Servlets, JSP's + or when script portlets are used, in order to avoid <CODE>OutOfMemoryError</CODE> errors. + By default, it is 64MB. Increasing it to be <CODE>-XX:MaxPermSize=128m</CODE> might be a good start. + Please see <a href="http://wiki.apache.org/tomcat/FAQ/Memory";>http://wiki.apache.org/tomcat/FAQ/Memory</a> for detail. + </p> + </subsection> + <subsection name="Advanced Build Options"> + <p> + By the command, `$mvn jetspeed:mvn -Dtarget=all', the <strong>jetspeed-archtype</strong> will build and install your custom portal project, initialize your database and finally deploy your portal and portlet application to your Tomcat. + However, during your continuous development, doing all tasks by the above command could be regarded as inefficient. + </p> + <p> + Therefore, <strong>jetspeed-archetype</strong> provides more advanced build options to fulfill various needs. You can build by setting a proper target you need in the following table: + <table> + <thead> + <tr> + <th>Target</th> + <th>Example command</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>install-pa</td> + <td><code>mvn jetspeed:mvn -Dtarget=install-pa</code></td> + <td>Cleans and builds the portlet application subproject.</td> + </tr> + <tr> + <td>install-portal</td> + <td><code>mvn jetspeed:mvn -Dtarget=install-portal</code></td> + <td>Cleans and builds the portal application subproject</td> + </tr> + <tr> + <td>install</td> + <td><code>mvn jetspeed:mvn -Dtarget=install</code></td> + <td>Does `install-pa' and `install-portal'.</td> + </tr> + <tr> + <td>db</td> + <td><code>mvn jetspeed:mvn -Dtarget=db</code></td> + <td>Initializes the database and seed the initial data for your custom portal.</td> + </tr> + <tr> + <td>portal-seed</td> + <td><code>mvn jetspeed:mvn -Dtarget=portal-seed</code></td> + <td>Just seeds the initial data for your custom portal without initializing the database.</td> + </tr> + <tr> + <td>deploy-pa</td> + <td><code>mvn jetspeed:mvn -Dtarget=deploy-pa</code></td> + <td>Deploys your custom portlet application.</td> + </tr> + <tr> + <td>deploy-portal</td> + <td><code>mvn jetspeed:mvn -Dtarget=deploy-portal</code></td> + <td>Deploys your custom portal.</td> + </tr> + <tr> + <td>portal-seed-dbpsml</td> + <td><code>mvn jetspeed:mvn -Dtarget=portal-seed-dbpsml</code></td> + <td>Seeds database-based pages data for your custom portal application.</td> + </tr> + <tr> + <td>deploy-portal-dbpsml</td> + <td><code>mvn jetspeed:mvn -Dtarget=deploy-portal-dbpsml</code></td> + <td>Deploys your custom portal with seeding database-based pages data.</td> + </tr> + <tr> + <td>all</td> + <td><code>mvn jetspeed:mvn -Dtarget=all</code></td> + <td>Installs and deploys your custom portal and custom portlet application, initializes and seeds the database.</td> + </tr> + </tbody> + </table> + </p> + </subsection> + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-ddl-plugin.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-ddl-plugin.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-ddl-plugin.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-ddl-plugin.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,34 @@ +<?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: jetspeed-db-ddl-plugin.xml 779358 2009-05-28 00:04:54Z ate $ +--> +<document> + <properties> + <title>Configuration and usage of the jetspeed-db:ddl Maven Plugin</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Configuration and usage of the jetspeed-db:ddl Maven Plugin"> + <p> + [TBD] + </p> + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-init-plugin.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-init-plugin.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-init-plugin.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-db-init-plugin.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,47 @@ +<?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: jetspeed-db-init-plugin.xml 779358 2009-05-28 00:04:54Z ate $ +--> +<document> + <properties> + <title>Configuration and usage of the jetspeed-db:init Maven Plugin</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </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> + <p> + [TBD] + </p> + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-deploy-plugin.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-deploy-plugin.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-deploy-plugin.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-deploy-plugin.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,34 @@ +<?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: jetspeed-deploy-plugin.xml 779358 2009-05-28 00:04:54Z ate $ +--> +<document> + <properties> + <title>Configuration and usage of the jetspeed-deploy:deploy Maven Plugin</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Configuration and usage of the jetspeed-deploy:deploy Maven Plugin"> + <p> + [TBD] + </p> + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-maven-plugins.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-maven-plugins.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-maven-plugins.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-maven-plugins.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,76 @@ +<?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: jetspeed-maven-plugins.xml 779358 2009-05-28 00:04:54Z ate $ +--> +<document> + <properties> + <title>Overview of the Jetspeed Maven Plugins</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </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-layout.html">Jetspeed Portal project layout</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>   <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 Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-mvn-plugin.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-mvn-plugin.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-mvn-plugin.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-mvn-plugin.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,633 @@ +<?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: jetspeed-mvn-plugin.xml 935689 2010-04-19 18:02:52Z taylor $ +--> +<document> + <properties> + <title>Automating Maven project builds using the jetspeed:mvn Maven Plugin</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </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="<targets combine.children="append">"> + <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><targets combine.children="append"></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=<target id></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> + <property-name>value</property-name></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><id/></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><depends/></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 <dir>./</dir></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><goals>goal1,goal2,goal3</goals></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><profiles>profile1,profile2,profile3</profiles></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 <useSettings>true</useSettings> 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>[email protected]@.database</code></strong>: + <source><![CDATA[<plugin> + <groupId>${pom.groupId}</groupId> + <artifactId>jetspeed-db-maven-plugin</artifactId> + <version>${pom.version}</version> + <configuration> + <connection> + <username>${[email protected]@.database.user}</username> + <password>${[email protected]@.database.password}</password> + <url>${[email protected]@.database.url}</url> + <driver>${[email protected]@.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><defaultGoal/></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 <useSettings/> 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 <mavenOpts/> configuration element value will be used. + </td> + </tr> + </table> + </subsection> + </section> + <section name="Usage"> + <subsection name="Showing the available targets"> + <p> + A very useful feature of the jetspeed:mvn plugin is that it can show the currently available targets, within the scope of the current Maven (sub) project, + using the optional commandline parameter <code><strong>-Dlist</strong></code>: + <source>$mvn jetspeed:mvn -Dlist</source> + </p> + <p> + As an example, for the Jetspeed project itself (2.2.1 release) the following output will be shown: + <source> +[INFO] [jetspeed:mvn] + +Available jetspeed:mvn targets: + testdb [testdb] + test [test] + proddb [proddb] + demo-install [demo-install] + demo-seed [demo-seed] + min-seed [min-seed] + demo-deploy [demo-deploy] + demo-deploy-min [demo-deploy-min] + demo-deploy-dbpsml [demo-deploy-dbpsml] + test-install [testdb, test-install] + demo-seed-dbpsml [proddb, demo-seed, demo-db, demo-seed-dbpsml] + min-seed-dbpsml [proddb, demo-seed, demo-db, min-seed-dbpsml] + demo-db [proddb, demo-seed, demo-db] + min-db [proddb, min-seed, min-db] + demo-db-psml [proddb, demo-seed, demo-db, demo-seed-dbpsml, demo-db-psml] + demo [demo-install, proddb, demo-seed, demo-db, demo-deploy, demo] + min [demo-install, proddb, demo-seed, demo-db, demo-deploy-min, min] + min-dbpsml [demo-install, proddb, demo-seed, demo-db, demo-deploy-min, demo-deploy-dbpsml, min-seed-dbpsml, min-dbpsml] + demo-dbpsml [proddb, demo-seed, demo-db, demo-seed-dbpsml, demo-db-psml, demo-deploy, demo-deploy-dbpsml, demo-dbpsml]</source> + </p> + <p> + The left column above shows the available targets to be executed using the <strong><code>-Dtarget=<target id></code></strong> commandline parameter.<br/> + The right column shows the actual chained set of targets which will be executed in order as result. + </p> + <p> + Complete documentation about these actual jetspeed project target definitions is provided on the <a href="maven-2-build.html">Building from Source</a> page. + </p> + </subsection> + <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> + <subsection name="Executing a target"> + </subsection> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-portal-resources.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-portal-resources.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-portal-resources.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-portal-resources.xml Thu Jul 16 21:01:09 2015 @@ -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: jetspeed-portal-resources.xml 779028 2009-05-27 06:38:26Z ate $ +--> +<document> + <properties> + <title>The jetspeed-portal-resources:jar artifact</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="The jetspeed-portal-resources:jar 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 a Maven artifact, the <strong><code>jetspeed-portal-resources:jar</code></strong>, + which can be used to only selectively use (unpack) needed resources for a specific target (artifact) or integration task. + </p> + <p> + Important and commonly used resources provided by the <code>jetspeed-portal-resources:jar</code> artifact are: + <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 like the <code>jetspeed-portal-resources:jar</code> artifact. + </p> + </section> + </body> +</document> \ No newline at end of file
