This document is a step by step guide to building a custom Apache Portals Jetspeed-2 portal with Maven-1. The Maven-1 project provided with this document will:
This document is for Maven-1 build systems. To build with Maven-2, see the accompanying document "Building Custom a Jetspeed Portal with Maven-2"
For documentation on deploying the WAR and EAR files created here, see the document "Deploying Jetspeed to Websphere"
This document will teach you how to build and configure a custom Jetspeed Portal and create deployable archives for Websphere 6.1 and Tomcat 5. The complete source code, projects and deployment environment are described in this document. Deployments are based upon the J2EE standard "Web Application" and "Enterprise Application" deployment. The build is based on the Apache Portals Jetspeed-2 "Maven-1 Custom Build".
Jetspeed is an open source project, thus all source code is freely available from Apache. See the website for more details: http://portals.apache.org/jetspeed-2/
This document assumes that the user is familiar with open source Java development. In particular the Apache Software Foundation (ASF) and the essential Apache open source projects:
This section shows how to configure under Windows XP for development, demo, testing and production environments. Since we are working with Java, the environment for Linux will not be much different although components like Eclipse and MySQL require Linux specific versions and setup.
When using properties files under Windows, please remember that Java requires you to use either the forward slash /, or double back slash \\ for file system paths. You cannot use a single back slash \. Using the back slash does not work with Java, since it is the escape sequence-character.
WRONG!!!!
my.files = \path\to\my\files\
RIGHT :)
my.files = /path/to/my/files/
It is strongly recommended to always use forward slashes, whether on Windows or Linux.
It is strongly recommended that all developers on the project use the same root directory for all project source and supporting files.
The distribution is a complete environment for software development, unit testing, system testing, and deploying to a production environment.
The system path will need to include Java, Maven and Ant.
Under Windows XP, the Environment Variables and the System Path is modified by going to the Start Menu -> Settings -> Control Panel -> System -> Advanced -> Environment Variables.
Note: You need administrative privileges to be allowed to modify system environment variables.
With these settings configured, you then have to make your system Windows PATH variable based on the home directories:
PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%MAVEN_HOME%\bin;C:\winnt\system32...
Note: make sure to put the new path elements in front of the existing path definition!
The build environment uses the Maven project management tool (http://maven.apache.org). One thing that Maven does well is managing Java jar files and maintaining versions of those files. Maven stores all jar files for almost every known open source project on the planet in a set of distributed repositories on the internet. Maven project descriptors reference specific versions of the jars, and the jars are downloaded to a local repository in order to build the system. By default Maven puts the repository under your Home directory which on Windows XP usually is found under the "Documents and Settings" directory.
Maven's behavior is for the most part customized through one project.properties and/or one or two build.properties files for each project.
Specific project properties are usually defined in a project.properties file within the project directory. User overrides of default and project properties can be defined in a build.properties file within the same project directory as well as in the user home directory. Properties defined in the build.properties in the user home directory will overrule any other property definitions.
Our project development environment is fully contained within one root project directory. In order to be able to have Maven not put its repository under the user home directory, we do need to specify a few properties in the user home build.properties.
The distribution contains a build.properties file under the etc directory which can be copied by every developer to its own home directory.
It defines the following general Maven-1 settings:
The build supports both Tomcat 5 and WebSphere 6.1. Because each server requires slightly different handling, there are two sets of property files. To switch between the two, run one of the two batch files:
The build requires a database installed on the local network. For the examples here, we will use an Oracle database although you can select other databases such as DB2 or MySQL.
The database properties are defined in build.properties.tomcat and build.properties.was. He is an example of using Oracle configuration parameters and MySQL commented out:
# -------------------------------------------------------------------------
# MySQL Database Setup
# -------------------------------------------------------------------------
org.apache.jetspeed.production.database.default.name=mysql
org.apache.jetspeed.production.database.url = jdbc:mysql://localhost/express
org.apache.jetspeed.production.database.driver = com.mysql.jdbc.Driver
org.apache.jetspeed.production.database.user = express
org.apache.jetspeed.production.database.password = xxxx
org.apache.jetspeed.production.jdbc.drivers.path=${express.home}/drivers/mysql-connector-java-3.1.7-bin.jar
# -------------------------------------------------------------------------
# Oracle Database Setup
# -------------------------------------------------------------------------
org.apache.jetspeed.production.database.default.name=oracle
org.apache.jetspeed.production.database.url = jdbc:oracle:thin:@svn.bluesunrise.com:1521:XE
org.apache.jetspeed.production.database.driver = oracle.jdbc.driver.OracleDriver
org.apache.jetspeed.production.database.user = fmr
org.apache.jetspeed.production.database.password = xxxx
org.apache.jetspeed.production.jdbc.drivers.path=etc/drivers/ojdbc14.jar
To have Eclipse use the local Maven repository which will contain all the jars needed for jetspeed-2, the portal and portlets, the MAVEN_REPO Classpath variable needs to be defined.
Open the Windows -> Preferences dialog and select the Java -> Build Path -> Classpath Variables node from the Preferences tree. Then use the New... button to add a new MAVEN_REPO variable pointing at your Maven home repository folder.
For building the portal, the Jetspeed-2 portal sources are not needed, but for debugging purposes, it can be helpful to have them checked out when trying to debug. The Jetspeed-2 sources, as well as those for the embedded pluto portlet container and portals bridges, can all be checked out from the svn.apache.org/repos/asf/portals repository root, similar to how the Jet Express sources are checked out.
The Jet Express portal project is a Maven based project. It builds the entire portal as well as the example portlet application. The main Jet Express project controls the entire build.
maven clean tomcat-all
This will clean, build and deploy the portal as well as deploy the example portlet application. Note: make sure to first once execute:
switchToTomcat.bat
To build WAR files:
maven clean was-war-all
To build EAR files:
maven clean was-ear-all
This will clean, build and deploy the portal as well as deploy the example portlet application. Note: make sure to first once execute:
switchToWebsphere.bat
Because the portal uses jetspeed-2 jars stored in the local maven repository, newer version of jetspeed-2 jars will not automatically be downloaded from the remote bluesunrise maven repository.
To synchronize with the latest available jetspeed-2 build, the sync-j2.cmd batch file needs to be executed which will clear out the jetspeed-2 jars from the local maven repository and upgrade to the latest jetspeed-2 maven plugin:
$WS_HOME\workspace\jetexpress>sync-j2.cmd
A following (full) portal build will then automatically download and use the latest jetspeed-2 jars.