Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-unpack-plugin.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-unpack-plugin.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-unpack-plugin.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/jetspeed-unpack-plugin.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,469 @@ +<?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-unpack-plugin.xml 1052139 2010-12-23 02:20:44Z ate $ +--> +<document> + <properties> + <title>Configuration and usage of the jetspeed-unpack:unpack Maven Plugin</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Configuration and usage of the jetspeed-unpack:unpack Maven Plugin"> + <p> + The Jetspeed Unpack Maven Plugin provides one goal: <strong><code>jetspeed-unpack:unpack</code></strong>, which can be used to extract selected resources + from a (remote) Maven artifact or an local (archive) file. + </p> + <p> + At the time this plugin was written, none of the required features was fully available from other (standard) Maven plugins. + </p> + <p> + Now, some of these features are also possible using the standard Maven Dependency Plugin + <a href="http://maven.apache.org/plugins/maven-dependency-plugin/unpack-mojo.html";>dependency:unpack</a> goal or the Remote Resources Plugin + <a href="http://maven.apache.org/plugins/maven-remote-resources-plugin/process-mojo.html";>remote-resources:process</a> goal. + </p> + <p> + However, this wasn't yet the case initially, and still the jetspeed-unpack plugin is easier to configure and use.<br/> + Furthermore, the same functionallity as provided by this plugin is also available embedded within the <a href="jetspeed-db-init-plugin.html">jetspeed-db:iniit</a> plugin using + exactly the same configuration. + </p> + <p> + This plugin is intended to be used as attached to the Maven <strong><code>process-resources</code></strong> or possibly <strong><code>generate-resources</code></strong> + lifecycle phase for embedding pre-defined resources in a final Maven artifact like a war file, or use such resources for integration tasks like deploying (possibly filtered) + configuration files to a target environment application server. + </p> + <subsection name="Side track: the jetspeed-portal-resources artifact"> + <p> + While this plugin is not dependent on the <strong><code>jetspeed-portal-resources</code></strong> artifact in anyway (nor on any other part of Jetspeed-2 for that matter), + it is primarily written and used for unpacking specific pre-packaged Jetspeed-2 Portal resources. + </p> + <p> + The <a href="jetspeed-portal-resources.html">Jetspeed Portal Resources</a> page further describes the jetspeed-portal-resources artifact and its intended usage. + </p> + </subsection> + </section> + <section name="Quick Overview"> + <p> + This is a listing of all the elements which can be configured for the jetspeed:unpack plugin: + </p> + <p> + <source><![CDATA[<plugin> + <groupId>org.apache.portals.jetspeed-2</groupId> + <artifactId>jetspeed-unpack-maven-plugin</artifactId> + <version>${org.apache.portals.jetspeed.version}</version> + <configuration> + + <unpack> + <artifact>...</artifact> + <file>...</file> + <targetDirectory>...</targetDirectory> + <overwrite>...</overwrite> + <resources combine.children="append"> + + <resource> + <path>...</path> + <destination>...</destination> + <overwrite>...</overwrite> + <flat>...</flat> + <include>...</include> + <exclude>...</exclude> + <name>...</name> + </resource> + ... + </resources> + </unpack> + + <skip>...</skip> + <verbose>...</verbose> + + </configuration> +</plugin>]]></source> + </p> + </section> + <section name="Configuration"> + <subsection name="Resource archive specification and references"> + <h4>Using Maven artifacts as resource archive</h4> + <p> + As with the <a href="jetspeed-db-init-plugin.html">jetspeed-db:init</a> plugin and the <a href="jetspeed-deploy-plugin.html">jetspeed-deploy:deploy</a> plugin, + the jetspeed-unpack plugin can (and primarily is intended to) use Maven Artifacts retrieved from the local Maven repository as resource (archives). + </p> + <p> + To use Maven artifacts as resource archive they need to be specified as plugin dependencies: + <source><![CDATA[<plugin> + <groupId>org.apache.portals.jetspeed-2</groupId> + <artifactId>jetspeed-unpack-maven-plugin</artifactId> + <version>${org.apache.portals.jetspeed.version}</version> + ... + <dependencies> + <dependency> + <groupId>org.apache.portals.jetspeed-2</groupId> + <artifactId>jetspeed-portal-resources</artifactId> + <version>${org.apache.portals.jetspeed.version}</version> + </dependency> + </dependencies> +</plugin>]]></source> + <em> + Note: Maven 2.0 (as of now, version 2.0.9) <strong>requires</strong> that for a plugin dependency its <version/> is defined, even if a default version is + configured in the project <dependencyManagement/> section for the same artifact.</em> + </p> + <p> + As standard Maven functionality, if such a dependency isn't available yet from the local Maven repository, it will automatically (try to) download it from a + remote Maven repository. + </p> + <h4>Referencing a plugin dependency as resource archive</h4> + <p> + To actually use a specific resource archive specified as a plugin dependency it can be referenced with: + <source><![CDATA[<artifact>${groupId}:${artifactId}:${packaging}</artifact>]]></source> + <em>Note: the default packaging of a dependency is <strong><code>jar</code></strong></em> + </p> + <p> + Using the <strong><code>jetspeed-portal-resources</code></strong> artifact as example, its artifact <em>reference</em> configuration would be: + <source><![CDATA[<artifact>org.apache.portals.jetspeed-2:jetspeed-portal-resources:jar</artifact>]]></source> + </p> + <p> + Note: the same type of definition and usage of (remote) Maven repository artifacts is also used by the <a href="jetspeed-db-init-plugin.html">jetspeed-db:init</a> and + <a href="jetspeed-deploy-plugin.html">jetspeed-deploy:deploy</a> plugins. + </p> + <h4>Using a local file archive</h4> + <p> + Alternatively, it is also possible to directly use local archive files, in which case a <strong><code>file</code></strong> + element should be specified instead of an <strong><code>artifact</code></strong> element: + <source><![CDATA[<file>localArchiveFilePath</file>]]></source> + </p> + </subsection> + <subsection name="Plugin configuration"> + <p> + The jetspeed-unpack plugin allows two general options to be configured besides specific <strong><code>unpack</code></strong> configurations: + </p> + <table> + <tr> + <th>Element</th> + <th width="90%">Description</th> + </tr> + <tr> + <td>skip</td> + <td> + <code>default: false</code><br/> + This optional element is primarly intended to allow skipping plugin execution under certain conditions, like <em>not</em> extracting resources + which are only needed when actually performing unit tests: + <source><![CDATA[<phase>process-test-resources</phase> + <configuration + <skip>${maven.test.skip}</skip> + ... + </configuration>]]></source> + Maven always invokes plugins attached to the <strong><code>process-test-resources</code></strong> phase, regardless if it actually is going to execute + unit tests. + </td> + </tr> + <tr> + <td>verbose</td> + <td> + <code>default: false</code><br/> + When unpacking resources, the <strong><code>verbose</code></strong> setting controls if detailed logging is performed which files are extracted.<br/> + </td> + </tr> + </table> + </subsection> + <subsection name="unpack configuration"> + <p> + As already described above, the actual resource archive to unpack from has to be specified either as <strong><code>artifact</code></strong> reference or + local <strong><code>file</code></strong>. + </p> + <p> + Additionally, two other optional unpack configuration elements can be speficied: + </p> + <table> + <tr> + <th>Element</th> + <th width="90%">Description</th> + </tr> + <tr> + <td>targetDirectory</td> + <td> + <code>default: ${project.build.directory}</code><br/> + The targetDirectory is used as <strong><em>base</em></strong> directory under which the selected resources from the resource archive will be extracted.<br/> + If this directory does not yet exist, it will be created by the plugin automatically before (possibly) extracting resources. + </td> + </tr> + <tr> + <td>overwrite</td> + <td> + <code>default: true</code><br/> + When a selected resource from the resource archive already exists in its target directory, the overwrite setting will determine if the existing resource + is overwritten, even if it has a more recent timestamp than the archived resource.<br/> + Note: if the archived resource has a more recent timestamp the existing resource will <em>always</em> be overwritten.<br/> + This setting can also be overruled for specific <strong><code>resource</code></strong> configurations (see below). + </td> + </tr> + </table> + </subsection> + <subsection name="<resources combine.children="append">"> + <p> + A potentially very important part of the configuration is the <strong><code>combine.children="append"</code></strong> attribute specified + for the <strong><code>resources</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 resources 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>resource</code></strong> element to prevent "merging in" property values from <em>unrelated</em> previously defined resource 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> + For the jetspeed-unpack plugin defining this attribute is recommended <em><strong>unless</strong></em> only one, or exactly similar resource child elements are configured + (e.g. using all the same set of elements). + </p> + </subsection> + <subsection name="resource configuration"> + <p> + The final part of the jetspeed-unpack plugin configuration concern the actual resoure(s) to unpack: + <source><![CDATA[<resource> + <path>/conf/tomcat</path> + <destination>tomcat</destination> + <include>context.xml</include> +</resource>]]></source> + The above example will extract the context.xml resource from the conf/tomcat folder within the resource archive and write it to a sub directory tomcat of the project + build directory or otherwise specified (base) targetDirectory. + </p> + <p> + Note: it is not required to specify any resource configuration. If none is specified <em>all</em> resources from the resource archive will be extracted! + </p> + <p> + The following (all optional) elements can be defined for a specific <strong><code>resource</code></strong> configuration: + </p> + <table> + <tr> + <th>Element</th> + <th width="90%">Description</th> + </tr> + <tr> + <td>path</td> + <td> + <code>default: /</code><br/> + The path specifies the sub folder within the resource archive as (base) path to search resources to extract. + </td> + </tr> + <tr> + <td>destination</td> + <td> + <code>default: ${configuration.targetDirectory}</code><br/> + If defined, the destination specifies the sub directory of the default project build directory or the otherwise specified <strong><code>targetDirectory</code></strong> + of the plugin where the matched resource(s) will be unpacked. + </td> + </tr> + <tr> + <td>overwrite</td> + <td> + <code>default: ${unpack.overwrite}</code> + If defined, overwrite overrules the default overwrite setting of the unpack element (see above). + </td> + </tr> + <tr> + <td>flat</td> + <td> + <code>default: false</code><br/> + By default resources to be extracted from the resource archive are written out to a sub directory of the target destination directory (see above) using their + relative position of the (base) path within the resource archive where they have been looked up against.<br/> + For example, with the following (probably incorrect) resource configuration: + <source><![CDATA[<resource> + <path>conf</path> + <destination>tomcat</destination> + <include>tomcat/context.xml</include> +</resource>]]></source> + the matched context.xml resource will be written out to: ${targetDirectory}/tomcat/tomcat/context.xml<br/><br/> + For this kind of configurations (and sometimes these are needed), defining <flat>true<flat> will "drop" the relative position of the resource.<br/> + Then, only its entry name will be used, resulting in (the probably desired): ${targetDirectory}/tomcat/context.xml<br/><br/> + Of course the same result can also (and even simpler) be achieved using: + <source><![CDATA[<resource> + <path>conf</path> + <include>tomcat/context.xml</include> +</resource>]]></source> + </td> + </tr> + <tr> + <td>include</td> + <td> + <code>default: ${resource.path}/**</code><br/> + The include element can define a comma separated list of resources to extract.<br/> + These may contain (standard Ant like) wildcards and sub folder references relative to the (base) path sub folder within the resource archive: + <source><![CDATA[<include>profile.xml,security*.xml,boot/*.xml</include>]]></source> + </td> + </tr> + <tr> + <td>exclude</td> + <td> + <code>default: <em>none</em></code><br/> + Potentially mached resources to extract (see include above) may be excluded from extraction using the exclude element.<br/> + Like with the include element, the exclude element can define a comma separated list of resources to <em>exclude</em>. + These also may contain (standard Ant like) wildcards and sub folder references relative to the (base) path sub folder within the resource archive: + <source><![CDATA[<exclude>security-spi*.xml,security-managers.xml</exclude>]]></source> + </td> + </tr> + <tr> + <td>name</td> + <td> + <code>default: <em>none</em></code><br/> + New file name for single resource extracted from the resource archive: + <source><![CDATA[<name>j2-seed.xml</name>]]></source> + </td> + </tr> + </table> + <p> + As can be determined from the above, as all resource configuration elements are optional, specifying an empty <resource/> definition will simply + extract all the resources from the archive to the targetDirectory. + </p> + </subsection> + </section> + <section name="Examples"> + <subsection name="Unpacking of jetspeed unit test resources"> + <p> + The following example taken from the Maven project file for the jetspeed-profiler component extracts several Spring assembly files, all files from the db-ojb folder + and the seed/min/j2-seed.xml file to the project testOutputDirectory as needed for running the unit tests: + <source><![CDATA[<plugin> + <groupId>${pom.groupId}</groupId> + <artifactId>jetspeed-unpack-maven-plugin</artifactId> + <version>${pom.version}</version> + <executions> + <execution> + <id>unpack-test-resources</id> + <goals> + <goal>unpack</goal> + </goals> + <phase>process-test-resources</phase> + <configuration> + <skip>${maven.test.skip}</skip> + <unpack> + <artifact>org.apache.portals.jetspeed-2:jetspeed-portal-resources:jar</artifact> + <targetDirectory>${project.build.testOutputDirectory}</targetDirectory> + <resources> + <resource> + <path>assembly</path> + <include>profiler.xml,transaction.xml,cache.xml,security-*.xml,boot/datasource.xml</include> + </resource> + <resource> + <path>db-ojb</path> + </resource> + <resource> + <path>seed/min</path> + <include>j2-seed.xml</include> + </resource> + </resources> + </unpack> + </configuration> + </execution> + </executions> +</plugin]]></source> + The interesting part of this example is that <em><strong>NO</strong></em> resource archive is specified! + </p> + <p> + But the above example actually does work because the root Maven project file for the Jetspeed-2 Portal project already defined the jetspeed-portal-resources artifact + as default dependency for the jetspeed-unpack plugin in its dependencyManagement section: + <source><![CDATA[<plugin> + <groupId>org.apache.portals.jetspeed-2</groupId> + <artifactId>jetspeed-unpack-maven-plugin</artifactId> + <version>${pom.version}</version> + <dependencies> + <dependency> + <groupId>${groupId}</groupId> + <artifactId>jetspeed-portal-resources</artifactId> + <version>${pom.version}</version> + </dependency> + </dependencies> +</plugin>]]></source> + But please note: this is a special use-case which only works when only one dependency is (pre)configured. + </p> + </subsection> + <subsection name="Unpacking the tomcat context.xml to be filtered before deployment"> + <p> + A more elaborate and common use-case is extracting a specific resource during the generate-resources lifecycle phase so that it can be filtered + (using the standard Maven resources plugin): + <source><![CDATA[<plugins> + <plugin> + <groupId>org.apache.portals.jetspeed-2</groupId> + <artifactId>jetspeed-unpack-maven-plugin</artifactId> + <version>${org.apache.portals.jetspeed.version}</version> + <executions> + <execution> + <id>unpack-appserver</id> + <goals> + <goal>unpack</goal> + </goals> + <phase>generate-resources</phase> + <configuration> + <unpack> + <artifact>org.apache.portals.jetspeed-2:jetspeed-portal-resources:jar</artifact> + <resources> + <resource> + <path>conf</path> + <include>tomcat/context.xml</include> + </resource> + </resources> + </unpack> + </configuration> + </execution> + </executions> + <dependencies> + <dependency> + <groupId>org.apache.portals.jetspeed-2</groupId> + <artifactId>jetspeed-portal-resources</artifactId> + <version>${org.apache.portals.jetspeed.version}</version> + </dependency> + </dependencies> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-resources-plugin</artifactId> + <executions> + <execution> + <id>resources</id> + <goals> + <goal>resources</goal> + </goals> + <phase>process-resources</phase> + </execution> + </executions> + </plugin> +</plugins> +... +<resources> + <resource> + <directory>${project.build.directory}/tomcat</directory> + <targetPath>../resources</targetPath> + <filtering>true</filtering> + </resource> +</resources>]]></source> + This example is taken from a custom Maven project file invoked with the <a href="jetspeed-mvn-plugin.html">jetspeed-mvn</a> plugin for deploying a custom Jetspeed-2 Portal + on a Tomcat server. + </p> + <p> + The standard Maven Resources Plugin is also configured in this example because a custom jetspeed-mvn Maven project file is commonly configured using + <packaging>pom</packaging>.<br/> + Such custom jetspeed-mvn project files are used for executing specific integration tasks, not for producing a "normal" artifact like a jar or war file.<br/> + But as a pom project doesn't have the maven-resources-plugin attached to its lifecycle it needs to be configured directly to have it perform the needed + resource filtering during the process-resources phase. + </p> + </subsection> + </section> + </body> +</document>
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/maven-2-build.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/maven-2-build.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/maven-2-build.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/maven-2-build.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,493 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title> + Building Jetspeed 2.2 from Source with Maven-2 + </title> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + <person name="Ate Douma" email="[email protected]" /> + <person name="Woonsan Ko" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Building and Deploying Jetspeed 2.2 from Source with Maven-2"> + <subsection name="Prerequisites"> + <p>Building and deploying Jetspeed-2 from source has the following prerequisites:</p> + <ul> + <li>Java Development Kit 1.5</li> + <li><a class="externalLink" href="http://maven.apache.org/";>Apache Maven</a> 2.2.1+</li> + <li><a class="externalLink" href="http://tomcat.apache.org/";>Apache Tomcat</a> 6.0.33+</li> + <li>Configuration of the <code>org.apache.portals.jetspeed-2</code> Maven Settings pluginGroup, see: + <a href="index.html#PREREQUISITE:_configuration_of_the_Maven_Settings_pluginGroups">PREREQUISITE: configuration of the Maven Settings pluginGroups</a> + on the <em>Overview</em> page. + </li> + <li>Either a <a class="externalLink" href="http://portals.apache.org/jetspeed-2/download.html"; target="_blank">downloaded</a> release source distribution archive + or directly checked out from the ASF Subversion source respository using a SVN client tool.<br/> + You can checkout the sources from + <a class="externalLink" href='http://svn.apache.org/repos/asf/portals/jetspeed-2/portal/trunk/' target='_blank'>http://svn.apache.org/repos/asf/portals/jetspeed-2/portal/trunk/</a> + </li> + </ul> + </subsection> + <subsection name="Configuring the build environment"> + <p> + All the settings needed during the build and for a jetspeed demo Portal deployment need to be defined in a single file in the root folder + of the project: <strong><code>jetspeed-mvn-setttings.xml</code></strong>. <br/> + <em>Note: this file is not provided but needs to be created manually first.</em> + </p> + <p> + For convience however a sample file, <strong><code>jetspeed-mvn-setttings-sample.xml</code></strong> is + provided which can simply be copied to <strong><code>jetspeed-mvn-setttings.xml</code></strong>. + </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 are the location of the Derby database(s) and the deployment target directory + (<code>org.apache.jetspeed.server.home</code>): + <source><![CDATA[ +<properties> + ... + <!-- Your Tomcat Installation Path --> + <org.apache.jetspeed.server.home>/home/demo/tomcat-6</org.apache.jetspeed.server.home> + <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major> + + <!-- Production jdbc driver artifact properties --> + <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> + + <!-- Production database name, JDBC url, JDBC driver name and connection information --> + <org.apache.jetspeed.production.database.default.name>derby</org.apache.jetspeed.production.database.default.name> + <org.apache.jetspeed.production.database.url>jdbc:derby:/tmp/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> + + ... + + <!-- You can also configure test database properties below if you want to run unit tests. --> + + <!-- Test jdbc driver artifact properties --> + <org.apache.jetspeed.test.jdbc.driver.groupId>org.apache.derby</org.apache.jetspeed.test.jdbc.driver.groupId> + <org.apache.jetspeed.test.jdbc.driver.artifactId>derby</org.apache.jetspeed.test.jdbc.driver.artifactId> + <org.apache.jetspeed.test.jdbc.driver.version>10.3.2.1</org.apache.jetspeed.test.jdbc.driver.version> + + <!-- Test database name, JDBC url, JDBC driver name and connection information --> + <org.apache.jetspeed.test.database.default.name>derby</org.apache.jetspeed.test.database.default.name> + <org.apache.jetspeed.test.database.url>jdbc:derby:/tmp/derby/testdb;create=true</org.apache.jetspeed.test.database.url> + <org.apache.jetspeed.test.database.driver>org.apache.derby.jdbc.EmbeddedDriver</org.apache.jetspeed.test.database.driver> + <org.apache.jetspeed.test.database.user></org.apache.jetspeed.test.database.user> + <org.apache.jetspeed.test.database.password></org.apache.jetspeed.test.database.password> + ... +</properties>]]></source> + </p> + <p> + <em>Note: depending on your database platform, the value of the <code>org.apache.jetspeed.production.database.default.name</code> property + can be one of the followings depending on your database platform:</em> + <ul> + <li>db2</li> + <li>db2v8</li> + <li>derby</li> + <li>mssql</li> + <li>mysql</li> + <li>mysql5</li> + <li>oracle9</li> + <li>oracle10</li> + <li>postgresql</li> + <li>sapdb</li> + </ul> + For details about supported databases, refer to the <a href="http://db.apache.org/ddlutils/";>Apache DB Project - DdlUtils Homepage</a>. + </p> + <p> + The following <strong><code>jetspeed-mvn-settings.xml</code></strong> provides a sample configuration using a PostgreSQL database: + <source><![CDATA[ +<properties> + ... + <!-- Your Tomcat Installation Path --> + <org.apache.jetspeed.server.home>/home/demo/tomcat-6</org.apache.jetspeed.server.home> + <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major> + + <!-- Production jdbc driver artifact properties --> + <org.apache.jetspeed.production.jdbc.driver.groupId>postgresql</org.apache.jetspeed.production.jdbc.driver.groupId> + <org.apache.jetspeed.production.jdbc.driver.artifactId>postgresql</org.apache.jetspeed.production.jdbc.driver.artifactId> + <org.apache.jetspeed.production.jdbc.driver.version>8.3-603.jdbc3</org.apache.jetspeed.production.jdbc.driver.version> + + <!-- Production database name, JDBC url, JDBC driver name and connection information --> + <org.apache.jetspeed.production.database.default.name>postgresql</org.apache.jetspeed.production.database.default.name> + <org.apache.jetspeed.production.database.url>jdbc:postgresql://localhost/j2</org.apache.jetspeed.production.database.url> + <org.apache.jetspeed.production.database.driver>org.postgresql.Driver</org.apache.jetspeed.production.database.driver> + <org.apache.jetspeed.production.database.user>j2</org.apache.jetspeed.production.database.user> + <org.apache.jetspeed.production.database.password>j2</org.apache.jetspeed.production.database.password> + + ... + + <!-- You can also configure test database properties below if you want to run unit tests. --> + + <!-- Test jdbc driver artifact properties --> + <org.apache.jetspeed.test.jdbc.driver.groupId>postgresql</org.apache.jetspeed.test.jdbc.driver.groupId> + <org.apache.jetspeed.test.jdbc.driver.artifactId>postgresql</org.apache.jetspeed.test.jdbc.driver.artifactId> + <org.apache.jetspeed.test.jdbc.driver.version>8.3-603.jdbc3</org.apache.jetspeed.test.jdbc.driver.version> + + <!-- Test database name, JDBC url, JDBC driver name and connection information --> + <org.apache.jetspeed.test.database.default.name>postgresql</org.apache.jetspeed.test.database.default.name> + <org.apache.jetspeed.test.database.url>jdbc:postgresql://localhost/j2test</org.apache.jetspeed.test.database.url> + <org.apache.jetspeed.test.database.driver>org.postgresql.Driver</org.apache.jetspeed.test.database.driver> + <org.apache.jetspeed.test.database.user>j2test</org.apache.jetspeed.test.database.user> + <org.apache.jetspeed.test.database.password>j2test</org.apache.jetspeed.test.database.password> + ... +</properties>]]></source> + </p> + <p> + Alos, the following provides a sample configuration using a MySQL database: + <source><![CDATA[ +<properties> + ... + <!-- Your Tomcat Installation Path --> + <org.apache.jetspeed.server.home>/home/demo/tomcat-6</org.apache.jetspeed.server.home> + <org.apache.jetspeed.catalina.version.major>6</org.apache.jetspeed.catalina.version.major> + + <!-- Production jdbc driver artifact properties --> + <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> + + <!-- Production database name, JDBC url, JDBC driver name and connection information --> + <org.apache.jetspeed.production.database.default.name>mysql5</org.apache.jetspeed.production.database.default.name> + <org.apache.jetspeed.production.database.url>jdbc:mysql://localhost:3306/j2</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>j2</org.apache.jetspeed.production.database.user> + <org.apache.jetspeed.production.database.password>j2</org.apache.jetspeed.production.database.password> + + ... + + <!-- You can also configure test database properties below if you want to run unit tests. --> + + <!-- Test jdbc driver artifact properties --> + <org.apache.jetspeed.test.jdbc.driver.groupId>mysql</org.apache.jetspeed.test.jdbc.driver.groupId> + <org.apache.jetspeed.test.jdbc.driver.artifactId>mysql-connector-java</org.apache.jetspeed.test.jdbc.driver.artifactId> + <org.apache.jetspeed.test.jdbc.driver.version>5.1.6</org.apache.jetspeed.test.jdbc.driver.version> + + <!-- Test database name, JDBC url, JDBC driver name and connection information --> + <org.apache.jetspeed.test.database.default.name>mysql5</org.apache.jetspeed.test.database.default.name> + <org.apache.jetspeed.test.database.url>jdbc:mysql://localhost:3306/j2test</org.apache.jetspeed.test.database.url> + <org.apache.jetspeed.test.database.driver>com.mysql.jdbc.Driver</org.apache.jetspeed.test.database.driver> + <org.apache.jetspeed.test.database.user>j2test</org.apache.jetspeed.test.database.user> + <org.apache.jetspeed.test.database.password>j2test</org.apache.jetspeed.test.database.password> + ... +</properties>]]></source> + </p> + <p> + <em> + Note: To run unit tests properly with MySQL database, you should enable InnoDB storage engine and use InnoDB tables. + InnoDB is a transactional-safe (ACID compliant) storage engine for MySQL database. See the documentation of MySQL for details. + </em> + </p> + </subsection> + <subsection name="Configuring Tomcat"> + <p> + A few changes and additions are needed to the default provided configuration of Tomcat to support proper Portlet API session management requirements and + Jetspeed portlet application management integration: + </p> + <p> + <ul> + <li>In <strong><code><TOMCAT_HOME>/conf/server.xml</code></strong>:<br/> + Modify the Connector element (default on port 8080) by adding the following attribute and value: + <source>emptySessionPath="true"</source> + </li> + <li>In <strong><code><TOMCAT_HOME>/conf/context.xml</code></strong>:<br/> + Uncomment the following to disable session persistence across Tomcat restarts: + <source><![CDATA[<Manager pathname=""/>]]></source> + </li> + <li>Optional: in <strong><code><TOMCAT_HOME>/conf/tomcat-users.xml</code></strong>:<br/> + Select or add a specific Tomcat user with at least role <strong><code>manager-script</code></strong> to be used by Jetspeed to communicate with the Tomcat Manager application: + <source><![CDATA[<user username="j2deployer" password="<<em>strong</em> password<" roles="manager-script"/>]]></source> + Then, define this username and its password in the <strong><code>jetspeed.properties</code></strong> file read by + the portal at runtime, but overriding and more secret values can be specified in <strong><code>override.properties</code></strong>.<br/> + See for further information the <a href="../deployguide/guide-tomcat.html">Tomcat Manager and Jetspeed</a> section in the Deployers Guide. + </li> + </ul> + </p> + </subsection> + </section> + <section name="Building and installing Jetspeed Portal"> + <subsection name="Optional: Bootstrap build the Jetspeed Maven Plugins first"> + <p> + When building Jetspeed 2.2 from a released source distribution archive or a SVN checkout of a corresponding release tag the following step can be skipped. + </p> + <p>However, when building a specific Jetspeed 2.2.x SNAPSHOT or branch SVN checkout which has not (yet) been released, you will have to run the following command + first, but <em><strong>only</strong></em> the first time (for the checkout version): + <source>$mvn install -P init</source> + </p> + <p> + The above command will ensure the custom Jetspeed Maven Plugins as well as the portal resources <em>for this build version</em> are prebuild + and installed in your local Maven repository as they might not be available from a remote Maven repository. + </p> + <p> + <em>Without the above bootstrap build an initial/first <strong><code>$mvn clean</code></strong> execution might lead to a BUILD FAILURE: "A required plugin was not found" error.</em> + </p> + </subsection> + <subsection name="Standard Maven build & install"> + <p> + A full build and installation of all the Jetspeed-2 components into your local Maven repository is done using the standard Maven install goal: + <source>$mvn install</source> + </p> + </subsection> + <subsection name="Deploying the jetspeed Demo Portal"> + <p> + First make sure to setup Tomcat 6 (6.0.33+) locally and apply the above described Tomcat configuration changes first.<br/> + Also make sure to configure the appropriate Tomcat major version (<code>org.apache.jetspeed.catalina.version.major</code>) and installation path + (<code>org.apache.jetspeed.server.home</code>) in your local <strong><code>jetspeed-mvn-settings.xml</code></strong> file in the root of the Jetspeed project. + </p> + <p> + After first building and installing the Jetspeed project using <strong><code>$mvn install</code></strong> as described above, deploy the + Jetspeed Demo Portal to Tomcat using the following command: + <source>$mvn jetspeed:mvn -Dtarget=demo</source> + </p> + <p> + Thereafter start Tomcat (in a separate console):<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> + And after waiting a few seconds until Tomcat server <em>completed</em> starting up, the Jetspeed Demo Portal can be accessed through: + <source><a class="externalLink" href="http://localhost:8080/jetspeed";>http://localhost:8080/jetspeed</a></source> + </p> + <p> + For login, use one of the following username/password combinations: admin/admin, user/user, jetspeed/jetspeed + </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="Deploying a minimal Jetspeed Portal"> + <p> + If you don't need the demo portlet applications, you can also deploy Jetspeed with only the j2-admin portlet application using the following command instead: + <source>$mvn jetspeed:mvn -Dtarget=min</source> + </p> + </subsection> + </section> + <section name="Build and installation options"> + <subsection name="Overview"> + <p>Using the jetspeed:mvn plugin, several defined custom build and installation tasks (targets) are provided for the Jetspeed Portal project itself.</p> + <p> + The complete list of available targets can be queried using the special <strong><code>-Dlist</code></strong> command line parameter: + <source>$mvn -o jetspeed:mvn -Dlist</source> + The primary jetspeed:mvn targets are described in detail below. Please see the <a href="jetspeed-mvn-plugin.html">Mvn Plugin</a> configuration + documentation and the root project <code>pom.xml</code> build file for further reference. + </p> + </subsection> + <subsection name="Primary jetspeed:mvn Targets"> + <p> + There are four major modes the portal can be built and deployed under: + <ul> + <li>ui: full ui pipeline demo build</li> + <li>min-ui: minimal ui pipeline demo build</li> + <li>demo: full portal pipeline demo build</li> + <li>min: minimal portal pipeline demo build</li> + </ul> + Additionally, there are two Page Manager variants for each mode: + <ul> + <li>XML file system based PSML</li> + <li>Database PSML</li> + </ul> + The primary build targets that can be used to build and deploy all or parts of the portal are outlined here: + </p> + <div><table> + <tbody> + <tr> + <td> + <p><strong><tt>test</tt></strong></p> + </td> + <td> + <p> + Executing the <strong><code>test</code></strong> target will simply execute the standard Maven test goal within the current (sub module) project folder, <em>and</em> + enables the <strong><code>test</code></strong> profile. + </p> + <p> + Of course the same effect can be achieved by just executing <strong><code>$mvn test -P test</code></strong> but the primary reason for this target definition is + to be used as dependent target for other targets (see below). + </p> + </td> + </tr> + <tr> + <td> + <p><strong><tt>testdb, proddb</tt></strong></p> + </td> + <td> + <p> + Executing one of these targets will (re)create either a test or production database (schema), using the database configuration properties from + the <strong><code>jetspeed-mvn-settings.xml</code></strong> file.<br/> + </p> + <p> + <em>Note: this target can be executed from within any (sub) module folder within the project.</em> + </p> + </td> + </tr> + <tr> + <td> + <p><strong><tt>ui-seed, min-ui-seed, demo-seed, min-seed and ui-db, min-ui-db, demo-db, min-db</tt></strong></p> + </td> + <td> + <p> + Besides (re)creation a (production) database using the <strong><code>proddb</code></strong> target, the Jetspeed database also needs some initial data to be seeded + first to be able to run the Jetspeed Portal. The <strong><code>ui-seed, min-ui-seed, demo-seed, min-seed</code></strong> targets will take care of that using specific <strong><code>j2-seed.xml</code></strong> files. + </p> + <p> + These seed files are dynamically retrieved from a previously build and installed or downloaded <strong><code>jetspeed-portal-resouces:jar</code></strong> artifact where + the configured seed files are references relative to a specific folder within this resources artifact. + </p> + <p> + As the <strong><code>proddb</code></strong> target and the <strong><code>*-seed</code></strong> targets usually are + executed together, the <strong><code>ui-db, min-ui-db, demo-db, min-db</code></strong> targets are also defined to allow execution those + as a single target. + </p> + </td> + </tr> + <tr> + <td> + <p><strong><tt>demo-install</tt></strong></p> + </td> + <td> + <p> + This target will simply invoke the default Maven goal, (which is <em>install</em>), against the <strong><code>applications/jetspeed-demo</code></strong> module pom.xml. + </p> + </td> + </tr> + <tr> + <td> + <p><strong><tt>ui, min-ui, demo, min</tt></strong></p> + </td> + <td> + <p> + These targets will perform the actual deployment of the Jetspeed Portal to the Tomcat installation along with all database configuration and seeding. The XML file system based PSML implementation is used and its pages (re)deployed by default. + </p> + <p> + <em>Note: executing these targets directly assumes all the required Jetspeed artifacts already are build and installed.</em> + </p> + </td> + </tr> + <tr> + <td> + <p><strong><tt>ui-nodb, min-ui-nodb, demo-nodb, min-nodb</tt></strong></p> + </td> + <td> + <p> + These targets only perform the deployment of the Jetspeed Portal. The database is left untouched, (the XML file system based PSML pages are redeployed). + </p> + </td> + </tr> + <tr> + <td> + <p><strong><tt>ui-dbpsml, min-ui-dbpsml, demo-dbpsml, min-dbpsml</tt></strong></p> + </td> + <td> + <p> + These targets are variants of the <strong><code>ui, min-ui, demo, min</code></strong> targets for the Database PSML configuration, (its pages are seeded into the database); + </p> + </td> + </tr> + <tr> + <td> + <p><strong><tt>ui-dbpsml-nodb, min-ui-dbpsml-nodb, demo-dbpsml-nodb, min-dbpsml-nodb</tt></strong></p> + </td> + <td> + <p> + These targets are variants of the <strong><code>ui-nodb, min-ui-nodb, demo-nodb, min-nodb</code></strong> targets for the Database PSML configuration, (its pages are not seeded into the database); + </p> + </td> + </tr> + </tbody> + </table></div> + </subsection> + </section> + + <section name="Test building Jetspeed Portal"> + + <subsection name="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 <strong><em>every time!</em></strong> </p> + <p>But if you are a Jetspeed committer or otherwise would like to run the test-cases anyway, the <em>testdb</em> jetspeed:mvn target can be used to setup and initialize the test database: + <source>$mvn jetspeed:mvn -Dtarget=testdb</source> + </p> + <p>Or you can run the following command to automatically execute the <em>testdb</em> target first before running a test build: + <source>$mvn jetspeed:mvn -Dtarget=test-install</source> + </p> + <p> + <em>Note: 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> + <p> + <em> + Additional note: Probably you need to configure some memory settings for maven to run all the tests properly because some test cases require more memory than the default memory size. + You can configure memory settings for maven by setting the environment variable 'MAVEN_OPTS'. For example: + <source>$export MAVEN_OPTS="-Xmx128m -XX:MaxPermSize=128m"</source> + </em> + </p> + </subsection> + </section> + <section name='Maven Profiles'> + <p>The following profiles can be supplied when building.</p> + <div> + <table> + <tbody> + <tr> + <td> + <p> <strong><tt>mvn -P all</tt></strong> </p> + </td> + <td> + <p> specified that all modules (the API, plugins, portal resources, commons, components and applications) be built.</p> + </td> + </tr> + <tr> + <td> + <p> <strong><tt>mvn -P init</tt></strong> </p> + </td> + <td> + <p> specified some modules to be initialized first (the API, plugins and portal resources) </p> + </td> + </tr> + <tr> + <td> + <p> <strong><tt>mvn -P test</tt></strong> </p> + </td> + <td> + <p> specified that all modules (the API, plugins, portal resources, commons, components and applications) be built, with the property setting, <b>-DskipTests=false</b></p> + </td> + </tr> + </tbody> + </table> + </div> + <subsection name='Additional Notes'> + <ul> + <li><b>mvn -P test</b> and <b>mvn -DskipTests=false</b> are equivalent.</li> + <li><b>mvn -P test -Dtest=MyTest</b> will execute a single test or matching tests if Ant wildcards are used. </li> + <li>Due to forking bugs in the Surefire Maven2 test runner plugin, test output, (e.g. System.out.println()), is not echoed to the build shell. If you wish to see console output for component tests, temporarily comment out the <forkMode> + elements in the components/pom.xml and the components pom.xml and run single tests. Note: the forking is required to run multiple tests. + </li> + <li><p> The <strong><tt>-o</tt></strong> offline option can be specified with the commands documented here to force Maven2 to use only the local repository. This can be invaluable in the event the main Maven2 repositories are down and the build insists upon validating a missing or troublesome POM. </p> + </li> + </ul> + </subsection> + </section> + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/project-layout.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/project-layout.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/project-layout.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/project-layout.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,170 @@ +<?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: project-layout.xml 779028 2009-05-27 06:38:26Z ate $ +--> +<document> + <properties> + <title>Standard layout of Jetspeed Portal Maven projects</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Standard layout of Jetspeed Portal Maven projects"> + <p> + A typical custom Jetspeed Portal project usually contains a module (sub project) for building and configuring the custom Jetspeed Portal + itself as well as one or more modules for portlet application(s) to be deployed to the Jetspeed Portal. + </p> + <p> + The following standard project layout is provided as best practice and in line with standard Maven project guidelines. + It is also easily expandable and customizable to incorporate future changes to the project goals and requirements. + </p> + <p> + The <a href="jetspeed-archetype.html">Jetspeed Archetype</a> Maven Plugin can be used as a quickstart to setting up a new custom Jetspeed Portal project + and will create a project structure using this standard layout. Furthermore, it will contain a typical and default setup and configuration for the + <a href="jetspeed-maven-plugins.html">Jetspeed Maven Plugins</a> for automating common Portal deployment and integration tasks using Maven itself. + </p> + <subsection name="The master project"> + <p> + To support central management and configuration of all or most of the individual (Maven) project artifacts and (Jetspeed) integration tasks, a + master/root Maven project pom.xml is used of type <packaging>pom</packaging>. + </p> + <p> + This root project will contain one or more modules (sub projects), which will have this root project defined as their parent + project. This way, all artifacts will be buildable and installable directly from the root project, and (Jetspeed) integration tasks + can be executed from anywhere within this project structure using the <a href="jetspeed-mvn-plugin.html">jetspeed:mvn plugin</a>. + </p> + <p> + In addition to the "standard" pom.xml project file(s), one or more custom jetspeed-mvn-${target name}-pom.xml project files can be defined, + as well as corresponding jetspeed-mvn[...].properties files and even a custom override of the Maven user settings.xml with a jetspeed-mvn-settings.xml file. + </p> + <p> + The custom jetspeed-mvn[...].properties and custom jetspeed-mvn-settings.xml files will serve as default and fallback configuration automatically + looked up through the project parent chain if a sub project doesn't provide these by itself when executing a <a href="jetspeed-maven-plugins.html">jetspeed:mvn</a> + invoked target task against a sub project. + </p> + </subsection> + <subsection name="The portal sub project module"> + <p> + For building and configuring the custom Jetspeed portal itself, as well as configuring and running Jetspeed Portal specific integration tasks, + the root project contains a "portal" subproject module. As a Jetspeed Portal is "just" a web application, <packaging>war</packaging> + is used for its pom.xml. + </p> + <p> + For building the custom Jetspeed Portal war artifact, the war overlay mechanism is used in the pom.xml, using the Jetspeed-2 provided + <code>org.apache.portals.jetspeed-2:jetspeed:war</code> artifact as overlay. + Note: this jetspeed war <em>only</em> contains the default (demo) Jetspeed Portal web application resources. + </p> + <p> + For pulling in the required portal application jar dependencies (to be put under its WEB-INF/lib) folder, the pom.xml contains a dependency on the + <code>org.apache.portals.jetspeed-2:jetspeed-dependencies:pom</code> artifact. + </p> + <p> + The advantage of separating the dependencies from the default jetspeed application war is that the jetspeed-dependencies dependency itself can be further restricted + or overridden within the pom. This wouldn't be possible (using standard Maven configuration) when these dependencies were incorporated in the default jetspeed war. + </p> + </subsection> + <subsection name="Portlet Application sub project module(s)"> + <p> + For building additional portlet applications to be deployed on the custom Jetspeed Portal, one or more additional "portlet application" subproject modules + can be added to the root project (note: a common abbriviation for "portlet application" is "pa"). As a pa also is "just" a web application, again + <packaging>war</packaging> is used for their pom.xml. + </p> + <p> + And, like with the portal module, a pa module can contain, in addition to the "standard" pom.xml, one or more custom jetspeed-mvn-${target name}-pom.xml + project files, as well as corresponding jetspeed-mvn[...].properties or even a custom override of the Maven user settings.xml with a (module specific) + jetspeed-settings.xml file. + </p> + <p> + For a portlet application module, this really is optional and often not needed, as typically just the pa war file needs to be deployed. + </p> + <p> + A common use-case where additional integration tasks might be needed however is when the pa defines and uses a custom database back-end + (or likewise: ldap, JCR etc.) which needs to be setup/created/upgraded or whatever. If an appropriate Maven plugin is available for performing + such an integration task (e.g. like the <a href="jetspeed-db-init-plugin.html">jetspeed-db:init plugin</a>), standardizing and automating the execution of such + tasks using the <a href="jetspeed-mvn-plugin.html">jetspeed:mvn plugin</a> should be very easy. + </p> + </subsection> + </section> + <section name="Conceptable project layout and contents"> + <p> + Using the above specification a conceptable custom Jetspeed Portal layout and its contents will look like the following: + </p> + <source><![CDATA[ +/my-portal-project + | pom.xml // standard maven root pom for the my-portal project + | jetspeed-mvn.settings.xml // project scoped maven settings configuration used for jetspeed:mvn target execution + | jetspeed-mvn-<target name>-pom.xml // custom pom providing the "build" tasks for a global/generic jetspeed:mvn target(s) + | jetspeed-mvn.properties // default properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}.properties // default ${target name} specific properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}-${target id}.properties // default ${target id} specific properties for jetspeed:mvn target execution + + /my-portal + | pom.xml // standard maven my-portal war pom using a war overlay mechanism + | jetspeed-mvn.settings.xml // my-portal scoped maven settings configuration used for jetspeed:mvn target execution + | jetspeed-mvn-${target name}-pom.xml // custom pom providing the "build" tasks for my-portal specific jetspeed:mvn target(s) + | jetspeed-mvn.properties // my-portal specific properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}.properties // my-portal and ${target name} specific properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}-${target id}.properties // my-portal and ${target id} specific properties for jetspeed:mvn target execution]]> + + /my-pa1 + | pom.xml // standard maven my-pa1 war pom + | jetspeed-mvn.settings.xml // my-pa1 scoped maven settings configuration used for jetspeed:mvn target execution + | jetspeed-mvn-${target name}-pom.xml // custom pom providing the "build" tasks for my-pa1 specific jetspeed:mvn target(s) + | jetspeed-mvn.properties // my-pa1 specific properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}.properties // my-pa1 and ${target name} specific properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}-${target id}.properties // my-pa1 and ${target id} specific properties for jetspeed:mvn target execution + + /my-pa2 + | pom.xml // standard maven my-pa2 war pom + | jetspeed-mvn.settings.xml // my-pa2 scoped maven settings configuration used for jetspeed:mvn target execution + | jetspeed-mvn-${target name}-pom.xml // custom pom providing the "build" tasks for my-pa2 specific jetspeed:mvn target(s) + | jetspeed-mvn.properties // my-pa2 specific properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}.properties // my-pa2 and ${target name} specific properties for jetspeed:mvn target execution + | jetspeed-mvn-${target name}-${target id}.properties // my-pa2 and ${target id} specific properties for jetspeed:mvn target execution + </source> + </section> + <section name="Typical project layout and contents"> + <p> + In practice not all of the above possible layout structure and files will be needed. + </p> + <p> + A typical custom Jetspeed Portal project is much simpler and can look like the following: + </p> + <source><![CDATA[ +/my-portal-project + | pom.xml // standard maven root pom for the my-portal project + | jetspeed-mvn.settings.xml // project only maven settings configuration used for jetspeed:mvn target execution + | jetspeed-mvn-prod.settings.xml.sample // optional project only maven production settings *sample* configuration to be used for jetspeed:mvn target execution: + // typically, production settings contain security sensitive parameters which should not be + // committed to a version control system and a concrete jetspeed-mvn-prod.settings.xml would + // not be allowed to be committed. + // the sample configuration then just provides a template to be copied to jetspeed-mvn-settings.xml + // and further configured by the developer/deployer locally. + | jetspeed-mvn.properties // optional (default) properties used for jetspeed:mvn target execution + + /my-portal + | pom.xml // standard maven my-portal war pom using war overlay mechanism + | jetspeed-mvn-portal-pom.xml // custom pom providing all the "build" tasks for my-portal specific jetspeed:mvn targets, like using jetspeed-db and jetspeed-deploy plugins]]> + + /my-pa + | pom.xml // standard maven my-pa war pom + | jetspeed-mvn-pa-pom.xml // Custom pom providing the all the "build" tasks for my-pa specific jetspeed:mvn target(s), like using jetspeed-deploy plugin + </source> + <p> + The above example project layout is what the <a href="jetspeed-archetype.html">Jetspeed Archetype</a> Maven plugin (partly) generates, + where the "my-" prefix and the maven artifact coordinates (groupId,artifactId,version) are configurable. + </p> + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/the-need-for-a-custom-lifecycle.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/the-need-for-a-custom-lifecycle.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/the-need-for-a-custom-lifecycle.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-build/src/site/xdoc/the-need-for-a-custom-lifecycle.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,234 @@ +<?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: the-need-for-a-custom-lifecycle.xml 779028 2009-05-27 06:38:26Z ate $ +--> +<document> + <properties> + <title>The need for a custom Maven build lifecycle</title> + <authors> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="The need for a custom Maven build lifecycle"> + <p> + A standard Maven 2.0 project provides 3 <em>fixed</em> build "lifecycles" called clean, default and site.<br/> + See also: + <a href="http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html";>Introduction to the Build Lifecycle"</a> on the Maven website. + </p> + <p> + These standard build lifecycles all focus on, <em>and only on</em>, the project artifacts themselves. + This means the build lifecycle and all the possible configurations thereof really concerns the final artifacts and their metadata only, + <em>NOT</em> the (target) environment where it is intended to be used. + </p> + <p> + The final phase of the default lifecycle, <code>deploy</code>, concerns the deployment of project artifacts to a remote Maven repository. + The intended <em>usage</em> of deployed artifacts comes only after this phase, and is in general out-of-scope from the POV of Maven itself, + except when an artifact itself is used as dependency by another Maven project. (which actually is the most common, "expected" use-case). + </p> + <p> + For the default and most common Maven artifact type, <em>jar</em>, this is perfectly fine, but for application server integration frameworks like Jetspeed-2 Portal, + it is <em>NOT</em>. + </p> + <p> + In contrast to more generic low-level (development) frameworks like Springframework, Jetspeed-2 comes with a very specific set of components, usually + assembled and configured only on integration level. While Jetspeed-2 <em>itself</em> is assembled and configured using Maven-2 and Springframework on + a very low-level detail, it should require only a few specific configurations (and provide room for extensions) to adapt and integrate for a custom + project and its environment. + </p> + <p> + These custom project and enviroment specific changes/overrides and extensions should be configured separately and independently from the base + Jetspeed-2 Portal configuration to support clean and clear maintainenance of the custom project lifecycle itself. + </p> + <p>For these requirements, the standard provided Maven build lifecycles and extension points are (currently) falling a bit short.</p> + <subsection name="Ways to customize the Maven build lifecycle"> + <p>There are many ways to customize the Maven build lifecycle:</p> + <ol> + <li> + <b>Using (only) profiles</b> + <br /> + <p> + Profiles within a Maven project (pom.xml) file allows to augment or replace default lifecycle behavior, but <em>maintains</em> + the predefined lifecycle phase handling. And, because the default lifecycle already configures standard behavior, trying to achieve something very different + from this standard behavior (like deploying and configuring a complete Portal application for a specific application server) quickly becomes very + unwielding and difficult to setup and maintain (if properly doable at all). + </p> + <p> + </p> + </li> + <li> + <b>Using "standalone" plugins</b> + <br /> + <p> + An alternative is writing and/or leveraging so called "standalone" Maven plugins which run <em>outside</em> + a lifecycle. These plugins don't affect or are affected by the default lifecycle. But... with the current Maven 2.0 model they also only can have + a single configuration within a project (pom.xml) file. If many different tasks (and possible different environments) are needed, the configuration + quickly becomes very large and complex and/or requires splitting it up into multiple profile definitions. + But then, the complex configuration is only replaced by more complex and error prone (manual) build instructions for the end user. + </p> + <p> + Furthermore, as these plugins run outside any lifecycle, none of the standard Maven plugins can be leveraged (nor directly "invoked" which isn't + supported by Maven). Often needed standard functionality like the copying/filtering of resource files will have to be provided by the + standalone plugin itself too! + </p> + <p> + Finally, while a standalone plugin can "fork" off a default lifecycle (phase), this also means (potentially) <em>all</em> + the standard provided lifecycle behavior is executed too again, leading to the same problems as with the previous option (see: above). + </p> + </li> + <li> + <b>Adding additional dedicated sub projects</b> + <br /> + <p> + This is the "standard" Maven-2 solution if multiple "artifacts" are needed for a certain project: split the project up in additional sub projects, + each providing its own "dedicated" result (note: with Maven-1 it was easy and common practice to write custom jelly "goals" in maven.xml for this + purpose). + </p> + <p>While this is certainly a good solution, and allows to leverage the full Maven-2 feature set, it has several caveats too.</p> + <p> + First of all, it can clutter the project structure quite a bit when many different "tasks" are required. And, as these "tasks" usually + are not meant to be run automatically during the normal build lifecycle, they should not be configured as sub modules of a parent project but then + require manual navigation to and invocation of the developer. Using (again) multiple profiles (see above) to "merge" several of these + tasks in one common project (pom) file can "automate" this, but then requires the developer to know and specify each needed (combination of) profile(s) to + execute. + </p> + <p> + Additionally, while maybe "good" practice by itself, it usually requires all artifacts and resources needed for such a dedicated "task" sub project + are build and installed in the local or a remote Maven repository first. This potentially adds yet more complexity and redundance to a project + configuration when such resources already are available locally within the context of another (sub) project anyway. + </p> + </li> + <li> + <b>Using custom project (pom.xml) files</b> + <br /> + <p>Maven-2 allows execution of non-default (pom.xml) project files using a command line option (-f <project file>).</p> + <p> + This solution elevates some of the caveats of the previous solution: there is no need to split up a project into several sub projects as a custom + "task oriented" project file can directly access the project local resources. + </p> + <p>On the other hand, this solution requires using additional command line parameters and thus again more effort from the developer.</p> + </li> + <li> + <b>Using a custom lifecycle extension</b> + <br /> + <p> + Finally, it is possible to <em>replace</em> the default lifecycle of a project (pom.xml) file alltogether by using a custom <packaging> type. + </p> + <p> + Such a custom lifecycle definition must be provided through a custom plugin extension and specifically be configured within the project file itself. + And a custom lifecycle extension will have to provide the complete definition of all the intended behavior. If that includes "old" standard behavior (like + building and installing a war) such a solution quickly falls down to the first solution discussed above, although it allows more (but still fixed) + flexibility and choices for configuration. + </p> + <p> + Other caveats of this solution are that probably multiple custom lifecycles will be required (e.g. different ones for pom,war,jar,ear etc.), + and that (future) default IDE tooling support will be very unlikely. + </p> + </li> + </ol> + <p> + Of the above solution, solution 2 and 5 are the most difficult to maintain and use. Solution 3 or 4, possibly in combination with solution 1, + are more in line with the intended usage of Maven-2, but do have as major caveat that they require more complex manual (commandline) usage instructions. + </p> + <p> + What really is missing here is automation: scripting/configuration support for the different tasks and commandline + parameters as needed for a specific custom project and its target environment(s). + </p> + <p> + While writing custom shell scripts, or maybe even using a <a href="http://ant.apache.org";>Apache Ant</a> script, to automate the different Maven-2 commands + is very well doable, it will easily result in every project having its own custom (and thus different) way of doing things. + And, as it will depend on yet another build tool, environment incompatibility issues (e.g. bash scripts usually don't run on Windows) easily can make this even more + complex to maintain. + </p> + </subsection> + <subsection name="The jetspeed:mvn Maven Plugin - Automating Maven tasks using Maven"> + <p> + To "solve" these problems, the Jetspeed-2 provided solution is a custom Maven plugin, jetspeed:mvn, to automate Maven-2 execution from + within Maven itself, using a configuration <em>within</em> a (parent) project file very similar to Apache Ant target definitions. + </p> + <p> + The jetspeed:mvn plugin <em>is</em> a standalone plugin (see discussion above), but requires only a very straightforward configuration and + only one additional commandline parameter to be executed. + </p> + <p> + An example commandline usage and a part of the (simplified) configuration as used by the Jetspeed-2 project itself to build, install, + configure a database and finally deploy a full Jetspeed Demo Portal is: <source>$mvn jetspeed:mvn -Dtarget=demo</source> + <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>demo-install</id> + <dir>@rootdir@/applications/jetspeed-demo</dir> + </target> + <target> + <id>proddb</id> + <name>db-init</name> + <properties> + <database.type>production</database.type> + </properties> + </target> + <target> + <id>demo-seed</id> + <name>demo</name> + <dir>@rootdir@/applications/jetspeed-demo</dir> + <profiles>seed</profiles> + </target> + <target> + <id>demo-db</id> + <depends>proddb,demo-seed</depends> + </target> + <target> + <id>demo-deploy</id> + <name>demo</name> + <dir>@rootdir@/applications/jetspeed-demo</dir> + <profiles>deploy</profiles> + </target> + <target> + <id>demo</id> + <depends>demo-install,demo-db,demo-deploy</depends> + </target> + </targets> + </configuration> +</plugin>]]></source> + </p> + <p> + The above example configuration shows several target "tasks" which can optionally "depend" on other targets (tasks) which will automatically be executed first. + In addition, specific properties, profiles and goals can be also be defined which will be passed on to the Maven execution environment. + Furthermore, the location of another (possibly custom) project file to execute, and even a custom maven user settings file, can also be specified and used, + allowing <em>full</em> control of the target Maven execution environment. + </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 Plugin expands upon the standard Invoker Plugin by allowing to be invoked directly from the commandline and by providing a generic and + configurable <em>chaining</em> of execution targets. In a way this is similar to Apache Ant build scripts, but using the standard Maven-2 project + build lifecycle handling for the actually execution of the individual target tasks. + </p> + <p> + Full description and configuration definition for the jetspeed:mvn plugin is provided on the <a href="jetspeed-mvn-plugin.html">Mvn Plugin</a> + page and detailed usages are given on the <em>Building Jetspeed</em> menu pages. + </p> + </subsection> + </section> + </body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/pom.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/pom.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/pom.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/pom.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,65 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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: pom.xml 775033 2009-05-15 06:48:11Z taylor $ +--> +<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd";> + + <modelVersion>4.0.0</modelVersion> + <prerequisites> + <maven>2.0.9</maven> + </prerequisites> + + <artifactId>jetspeed-guide-deploy</artifactId> + <name>Jetspeed Deployment Guide</name> + <description>Jetspeed 2.2 Deployment Guide</description> + <packaging>pom</packaging> + <parent> + <artifactId>jetspeed-site-docs</artifactId> + <groupId>org.apache.portals.site</groupId> + <version>2.2</version> + </parent> + + <!-- this is for a bug Maven, see http://jira.codehaus.org/browse/MSHARED-18 + should be removed once Maven incorporates this bug in an official release--> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-site-plugin</artifactId> + <version>2.0</version> + </plugin> + </plugins> + </build> + + <reporting> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-project-info-reports-plugin</artifactId> + <reportSets> + <reportSet> + <reports> + </reports> + </reportSet> + </reportSets> + </plugin> + </plugins> + </reporting> + +</project> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/resources/images/FragmentDefs.png URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/resources/images/FragmentDefs.png?rev=1691449&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/resources/images/FragmentDefs.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream
