Quick guide to getting started with Java portal development

Basic outline of the steps

  1. Install Maven 2.0.6+
  2. Configure personal settings for Maven 2
  3. Install Eclipse and tools for Eclipse
  4. Install Tomcat 5.5+
  5. Configure personal settings for Tomcat
  6. Install Ant 1.7+
  7. Check out the source code from the code repository
  8. Install the Maven 2 dependencies into the local repository
  9. Create and initialize a working database
  10. Configure Tomcat server to run within Eclipse
  11. Basic commands for working with Tomcat running in Eclipse
  12. Basic commands for working with maven and tomcat from the command line
  13. Viewing the portal with the browser
  14. Useful debugging techniques
  15. Problems/solutions encountered while installing the platform

    Please refer to Pas Portal programming practices for details about the coding standards that the project would like to practice in order to achieve a consistent and high quality code base.


Install Maven 2.0.6+

We are not using the Eclipse plug-in for Maven due to problems experienced with other projects using this plug-in. Recommend that you use maven via the command line.


  1. Download Maven 2 from http://maven.apache.org/download.html.
  2. Unpack the downloaded distribution.
  3. Define a M2_HOME system variable.
  4. Add M2_HOME/bin to the system path.

For Mac, paste this into your ~/.profile file:

export M2_HOME="/Users/telsbot/apache-maven-2.2.1"  # change this to match your setting
export PATH=$M2_HOME/bin:$PATH

Then run source command to read in the changes in the .profile:

$ source ~/.profile

Here is a more detailed guide from the Maven 2 website http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html.

Configure personal settings for Maven 2

  1. Below is an example of some custom settings for Maven 2 specifically for my environment. This customization is done by adding a settings.xml file under the .m2 folder. In Unix like operating systems, .m2 is under your home folder. If you do not have the '.m2' directory you must create it using the following 2 commands:
  2. cd ~ // this command will change your directory to your home directory
  3. mkdir .m2 // this command will create the .m2 directory for you.
  4. These settings must match to your particular environment.
  5. Under the <server> element, you must specify the same <username> and <password> for your tomcat manager (which is detailed in a later step, pick something you wish to use).

    Do not change the value of the <id> element, it must be myserver.

  6. Under the <jdbc.url> element, you must specify a file path where your sail database file will reside. In the example, it is set to my home_folder/tomcat/db/ directory and sail_database as the filename. We are currently using a Java database HSQLDB which uses a file storage mechanism for the database.

You don't normally need to change the

${user.home}

except in the case of Windows, where you probably need to put in the full path.

Note: This page How to start up in the PAS or TELS configuration describes in more detail the two locations where the <context.config.class> must be changed from:

net.sf.sail.webapp.spring.impl.SpringConfigurationImpl

to

org.telscenter.sail.webapp.spring.impl.SpringConfigurationImpl

To enable the TELS configuration which adds the following functionality:


<settings>
    <servers>
        <server>
            <id>myserver</id>
            <username>myuser</username>
            <password>mypass</password>
        </server>
    </servers>

    <profiles>
        <profile>
            <id>databaseConfig</id>
            <activation>
                <activeByDefault />
            </activation>
            <properties>
                <db.vendor>hsqldb</db.vendor>
                <jdbc.url>
                    jdbc:hsqldb:file:${user.home}/tomcat/db/sail_database;shutdown=true
                </jdbc.url>
                <jdbc.driverClassName>
                    org.hsqldb.jdbcDriver
                </jdbc.driverClassName>
                <jdbc.username>sa</jdbc.username>
                <jdbc.password></jdbc.password>
                <hibernate.dialect>
                    org.hibernate.dialect.HSQLDialect
                </hibernate.dialect>
            </properties>
        </profile>

        <profile>
            <id>portalConfig</id>
            <activation>
                <activeByDefault />
            </activation>
            <properties>
                <context.config.class>
                    net.sf.sail.webapp.spring.impl.SpringConfigurationImpl
                </context.config.class>
            </properties>
        </profile>
    </profiles>

    <activeProfiles>
        <activeProfile>databaseConfig</activeProfile>
        <activeProfile>portalConfig</activeProfile>
    </activeProfiles>
</settings>


Install Eclipse and tools for Eclipse

  1. Download Eclipse from http://www.eclipse.org/downloads/. Get the "Eclipse IDE for Java EE Developers" version. Eclipse 3.4 (Ganymede),3.5 (Galileo) and 3.6 (Helios) have been reported to work. We recommend using version 3.6.
  2. Define Maven 2 local repository location and add to the Eclipse build classpath. Otherwise you will see lots of build errors. To do that, look under the Eclipse Menu Window->Preferences. Within the preferences, select Java->Build Path->Classpath. Click "New" to add a new variable. The Name must be M2_REPO and the Path should be where the Maven 2 local repository lives, usually home_folder/.m2/repository. Create a home_folder/.m2/repository if you don't have one.
  3. Install the Web Tools Platform (WTP), Spring IDE, and Subclipse for Eclipse. These Eclipse plug-ins provide a nicer view when working with files such as JSP, spring XML configurations, etc.

    You can install all these plug-ins using the Eclipse Update Manager. Instructions for installing Spring IDE are available at http://springide.org/project/wiki/SpringideCallistoInstall. The actual update site for Spring IDE is at http://springide.org/updatesite. Subclipse update site is at http://subclipse.tigris.org/update_1.6.x. WTP update site is at http://download.eclipse.org/webtools/updates/


Install Tomcat 5.5+

  1. Download Tomcat 5.5.x (requires java 1.4+) or Tomcat 6.0.x (requires java 1.5+) from http://tomcat.apache.org/. You can find out which version suits you by reading this page: http://tomcat.apache.org/whichversion.html. This tutorial assumes that you are using 6.0.
  2. Unpack the downloaded distribution. Read the setup documentation http://tomcat.apache.org/tomcat-6.0-doc/setup.html. You will need to set CATALINA_HOME and JAVA_HOME environment variables as specified in the documentation. We will be referring the directory where you unpacked Tomcat as CATALINA_HOME.

    For Mac, to set CATALINA_HOME and JAVA_HOME variables, add this into your ~/.profile file:

    export JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Home"
    export CATALINA_HOME="/Users/telsbot/apache-tomcat-6.0.29"    # change this to match your setting
    

    Then run source command to read in the changes in the .profile:

    $ source ~/.profile
    
  3. In CATALINA_HOME/conf/context.xml file, add the antiJARLocking and antiResourceLocking attributes and set them to true for the existing <Context> element. This prevents any problems with hot deployment in certain operating systems.

    <Context antiJARLocking="true" antiResourceLocking="true">
    ...
    </Context>


If you do not want to use Eclipse Tomcat integration, see Running Tomcat from a shell script for an example of how to manage tomcat with a shell script.

Configure personal settings for Tomcat

  1. In CATALINA_HOME/conf/tomcat-users.xml file, you need to add a new "manager" role as well as a new user that has been granted the manager role.

    <tomcat-users>
    ...
    <role rolename="manager"/>
    <user username="myuser" password="mypass" roles="manager"/>
    ...
    </tomcat-users>


    This username and password must match the one previously defined in .m2/settings.xml.

Install Ant 1.7+

  1. Download Ant from http://ant.apache.org/bindownload.cgi.
  2. Unpack the downloaded distribution.
  3. Define an ANT_HOME system variable.
  4. Add ANT_HOME/bin to the system path.

    For mac users, follow the M2_HOME example above.

    Here is a more detailed guide from the Ant website http://ant.apache.org/manual/index.html.

Check out the source code from the code repository

There is a publicly available anonymous read-only subversion repository at http://sailportal.googlecode.com/svn/trunk/ (i.e., you can check out the code but not commit). It can be checked out within Eclipse using the SVN browsing perspective, or from the command line, by running 'svn checkout http://sailportal.googlecode.com/svn/trunk/ sailportal-read-only'. If you would really like to have development access (i.e., permission to commit), please send an email request to pas-portal-dev@googlecode.com

If you'd like to check out a branch of the webapp and work with the latest version of webapp, substitute the repository url with http://sailportal.googlecode.com/svn/webapp/branches/webapp-3.0/

  1. copy src/main/resources/sendmail_sample.properties to src/main/resources/sendmail.properties and edit the mappings in the sendmail.properties file. This file stores configuration settings when email needs to be sent from the portal.
  2. copy src/main/resources/portal_sample.properties to src/main/resources/portal.properties and edit the mappings in the portal.properties file. This file is stores other portal settings like portal name.

Install the Maven 2 dependencies into the local repository

  1. You must manually download and install the Java Transaction API (JTA) jar due to licensing restrictions.
  2. Download Java Transaction API Specification 1.0.1B Class Files from http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html. You must accept the license agreement.
  3. Then, install it using the command:
    mvn install:install-file -DgroupId=javax.transaction -DartifactId=jta -Dversion=1.0.1B -Dpackaging=jar -Dfile=/path/to/jta-1_0_1B-classes.zip
    

Check to see if it is already installed

ls ~/.m2/repository/javax/transaction/jta
  1. Install the remaining Maven 2 dependency jars and run all the unit tests from the project directory.
    cd  /path/where/project/code/from/svn/resides
    mvn clean; mvn compile; mvn resources:resources
    

Create and initialize a working database

In order to swap MySQL for HSQL follow the instructions below and once you know the application works successfully using HSQL, you can follow the instructions in How to install and use MYSQL instead of HSQLDB as the portal's database to switch to MySQL.

  1. Create the necessary directories where your sail database will reside (specified in .m2/settings.xml previously).
  2. Use ant from the project directory to create a working database.
    cd  /path/where/project/code/from/svn/resides
    ant db.schema-export
    ant db.init
    

Configure Tomcat server to run within Eclipse

Pas Portal mode

  1. Modify src/main/webapp/WEB-INF/web.xml and replace the 2 occurrences of ${context.config.class} with the value "net.sf.sail.webapp.spring.impl.SpringConfigurationImpl"
<context-param>
    <param-name>contextConfigClass</param-name>
    <param-value>net.sf..sail.webapp.spring.impl.SpringConfigurationImpl</param-value>
</context-param>
<init-param>
    <param-name>contextConfigClass</param-name>
    <param-value>${net.sf..sail.webapp.spring.impl.SpringConfigurationImpl}</param-value>
</init-param>


TELS Portal mode

  1. Modify src/main/webapp/WEB-INF/web.xml and replace the 2 occurrences of ${context.config.class} with the value "org.telscenter.sail.webapp.spring.impl.SpringConfigurationImpl"
<context-param>
    <param-name>contextConfigClass</param-name>
    <param-value>org.telscenter.sail.webapp.spring.impl.SpringConfigurationImpl</param-value>
</context-param>
<init-param>
    <param-name>contextConfigClass</param-name>
    <param-value>${org.telscenter.sail.webapp.spring.impl.SpringConfigurationImpl}</param-value>
</init-param>


Create an eclipse workspace with the svn checkout of the portal webapp directory.

  1. Look under the Eclipse menu Window->Preferences (or Eclipse->Preferences. Within the preferences, select Server->Installed Runtime (Runtime Environments in Eclipse 3.4.x)
  2. Click Add to add a new server runtime.
  3. Select Apache->Apache Tomcat v5.5 and then click Next.
  4. Click Browse and select the Tomcat installation directory as required. Then click Finish and OK to finish the dialog.
  5. Look under the Eclipse menu Window->Show View->Other. Within the Show View dialog, select Server->Servers.
  6. In the Servers view, right click in the window underneath and select New->Server.
  7. Enter "localhost" into Server's host name box.
  8. Select Apache->Tomcat v5.5 Server and click Next
  9. Right click on the new server and select Add and then select the project from Available Projects and add to the Configured Projects
  10. Click Next and then Finish.

    You will be required to run "mvn resources:resources" from the command line if the project is built within Eclipse. Maven 2 is used to filter some resources and dynamically replace values in the source code from your personal .m2/settings.xml file. Every time Eclipse starts a clean build you need to perform the above action before you can deploy to the server, i.e., the first time you build the project and anytime thereafter when you clean the project in Eclipse.


Basic commands for working with Tomcat running in Eclipse

All the controls for interacting with Tomcat are done using the Servers view in Eclipse. There should be a defined server for "Tomcat v5.5 Server @ localhost".

Copying and replacing the resources for the web application.


mvn resources:resources


The web application needs to be "published" to the server to begin.

The server needs to be "started".

The web application needs to be "republished" whenever files have changed.

The server can be started in "debug" mode.

Basic commands for working from the command line.

mvn -Dwtpversion=1.5 eclipse:eclipse

And then refresh your project. Note that the version # above will change with the WTP version.

  1. Start tomcat:
    mytomcat.sh start
    

  2. Write the code (Use eclipse if you want here).
  3. Compile the code at the command line.
    mvn compile
    

  4. If your webapp is currently deployed, you will need to un-deploy it first before re-deploying it again.
    mvn tomcat:undeploy
    

    #Hot deploy a working copy of the webapp to the running tomcat:
    mvn war:exploded tomcat:exploded
    

  5. Test your webapp. The URL for the standard default tomcat setup is
    http://localhost:8080/webapp/
    

    If you have configured a different port and/or hostname, the URL must reflect your changes.
  6. Go back to the development step, there is no need to stop and re-start tomcat.
  7. Command to list currently deployed webapps in tomcat:
    mvn tomcat:list
    

  8. When you want to stop tomcat run:
    mytomcat.sh stop
    

Viewing the portal with the browser

  1. In your browser, point to http://localhost:8080/webapp/ for the home page.

Useful debugging techniques

Problems/solutions encountered during platform installation