Quickstart a new custom Jetspeed Portal project using the jetspeed-archetype Maven Plugin

Jetspeed-2.3 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.

This document will guide you how to run the command and the steps to create a sample portal named hello.

You need the following prerequisites:

Optional: Building and Installing Jetspeed-2 Maven Plugins

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.

Note: you may skip this section for simplicity in normal cases.

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:

$mvn install -P init

This will ensure the required Jetspeed-2 Maven plugins are build and installed as well as the jetspeed-portal-resources artifact.

Using the jetspeed-archetype Maven Plugin

To use jetspeed-archetype Maven Plugin, you can run a command like the following:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.0-alpha-4:generate \
    -DarchetypeGroupId=org.apache.portals.jetspeed-2 \
    -DarchetypeArtifactId=jetspeed-archetype \
    -DarchetypeVersion=2.3.0 \
    -DartifactId=hello \
    -Dpackage=org.example \
    -DgroupId=org.example -Dversion=1.0.0

In the above command, the variables, "artifactId", "package" and "groupId", are project-specific ones. So you should provide variables for your project.

By the way, the other variables in the above command are from the Maven Archetype Plugin Specification. Please refer to Maven Archetype Plugin homepage for details.

Generating Hello Portal Application Example

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,

$ 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.3.0 \
-DartifactId=hello \
-Dpackage=org.example \
-DgroupId=org.example -Dversion=1.0.0

Note: 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.

With the above command, the jetspeed-archetype 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):

Directory Description
hello Project root directory
hello/hello-portal Custom portal web application root directory
hello/hello-portal/src Source directory for custom portal
hello/hello-portal/src/main/webapp/WEB-INF/pages Source directory for custom PSML page sources
hello/hello-portal/src/sql/min Source directory for seeding initial database
hello/hello-pa Custom portlet application root directory
hello/hello-pa/src Source directory for custom portlet application

Building Hello Portal Application Example

To configure the generated portal project, you need to edit jetspeed-mvn-settings.xml file in the project root directory and change the following:

Property Description
org.apache.jetspeed.server.home The Tomcat server directory which is the target of the custom portal deployment.
org.apache.jetspeed.catalina.version.major The major version number of Tomcat. Supported values are 6 and 7. Default value is 6.
org.apache.jetspeed.production.jdbc.driver.groupId The groupdId of your JDBC driver. For example, this can be "org.apache.derby" for Apache Derby JDBC driver.
org.apache.jetspeed.production.jdbc.driver.artifactId The artifactId of your JDBC driver. For example, this can be "derby" for Apache Derby JDBC driver.
org.apache.jetspeed.production.jdbc.driver.version The version of your JDBC driver.
org.apache.jetspeed.production.database.default.name 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 Apache DB Project - DdlUtils Homepage.)
org.apache.jetspeed.production.database.url The JDBC URL for your database access.
org.apache.jetspeed.production.database.driver The JDBC driver class name for your database access.
org.apache.jetspeed.production.database.user The database user name for your database access.
org.apache.jetspeed.production.database.password The database user password for your database access.

Initially, the jetspeed-archetype generates a jetspeed-mvn-settings.xml to use Apache Derby like the following example:

<settings xmlns="http://maven.apache.org/POM/4.0.0">

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:

<settings xmlns="http://maven.apache.org/POM/4.0.0">

You can build and deploy your custom portal to your Tomcat installation by using the following command:

$mvn org.apache.portals.jetspeed-2:jetspeed-mvn-maven-plugin:mvn -Dtarget=all
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:
<settings xmlns="http://maven.apache.org/POM/4.0.0">
<!-- add the following line to shorten the command invoking the Jetspeed Maven Plugin. -->
Now you can use a shorter command like the following:
$mvn jetspeed:mvn -Dtarget=all

Start your Tomcat:
Note that the setting of CATALINA_OPTS is optional in the following examples. (See Note on Permanent Generation Size of Your JVM for detail.)

$ cd $TOMCAT_HOME/bin
$ export CATALINA_OPTS="-Xmx256m -XX:MaxPermSize=128m"
$ ./catalina.sh run

Use your custom portal: http://localhost:8080/hello

Note on Permanent Generation Size of Your JVM

Note: 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 OutOfMemoryError errors. By default, it is 64MB. Increasing it to be -XX:MaxPermSize=128m might be a good start. Please see http://wiki.apache.org/tomcat/FAQ/Memory for detail.

Advanced Build Options

By the command, `$mvn jetspeed:mvn -Dtarget=all', the jetspeed-archtype 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.

Therefore, jetspeed-archetype provides more advanced build options to fulfill various needs. You can build by setting a proper target you need in the following table:

Target Example command Description
install-pa mvn jetspeed:mvn -Dtarget=install-pa Cleans and builds the portlet application subproject.
install-portal mvn jetspeed:mvn -Dtarget=install-portal Cleans and builds the portal application subproject
install mvn jetspeed:mvn -Dtarget=install Does `install-pa' and `install-portal'.
db mvn jetspeed:mvn -Dtarget=db Initializes the database and seed the initial data for your custom portal.
portal-seed mvn jetspeed:mvn -Dtarget=portal-seed Just seeds the initial data for your custom portal without initializing the database.
deploy-pa mvn jetspeed:mvn -Dtarget=deploy-pa Deploys your custom portlet application.
deploy-portal mvn jetspeed:mvn -Dtarget=deploy-portal Deploys your custom portal.
portal-seed-dbpsml mvn jetspeed:mvn -Dtarget=portal-seed-dbpsml Seeds database-based pages data for your custom portal application.
deploy-portal-dbpsml mvn jetspeed:mvn -Dtarget=deploy-portal-dbpsml Deploys your custom portal with seeding database-based pages data.
all mvn jetspeed:mvn -Dtarget=all Installs and deploys your custom portal and custom portlet application, initializes and seeds the database.