• How to install the portal for development purposes
Skip to end of metadata
Go to start of metadata

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

    Important

    Icon

    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+

Warning

Icon

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.

Mac tip

Icon

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

~/.profile

Then run source command to read in the changes in the .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).

    Warning

    Icon

    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.

Important

Icon

You don't normally need to change the

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:

  • more grading
  • UI enhancements
  • TELS workgroups include a reference to a class period
  • added teacher, student, and researcher user roles


.m2/settings.xml


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.

    Useful Information

    Icon

    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.

    Mac tip

    Icon

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

    ~/.profile

    Then run source command to read in the changes in the .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.
    CATALINA_HOME/conf/context.xml

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


Icon

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.
    CATALINA_HOME/conf/tomcat-users.xml

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


    Warning

    Icon

    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.
    Icon

    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

  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"
src/main/webapp/WEB-INF/web.xml
src/main/webapp/WEB-INF/web.xml


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"
src/main/webapp/WEB-INF/web.xml
src/main/webapp/WEB-INF/web.xml


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.

    Warning

    Icon

    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.

  • Right click on the server and select Publish.

The server needs to be "started".

  • Right click on the server and select Start.

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

  • Right click on the server and select Publish.

The server can be started in "debug" mode.

  • Right click on the server and select Debug.

Basic commands for working from the command line.

  • Maven 2 has an Eclipse plugin that supports the Web Tools Project (WTP) that sets the project build classpath based on the dependencies listed in pom.xml. Just run:

mvn -Dwtpversion=1.5 eclipse:eclipse

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

  • The basic development work flow consists of:
  1. Start tomcat:

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

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

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

  5. Test your webapp. The URL for the standard default tomcat setup is

    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:

  8. When you want to stop tomcat run:

Viewing the portal with the browser

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

Useful debugging techniques

  • The Console view in Eclipse displays all the output messages from Tomcat's standard out. Set the Log4J output level to DEBUG for verbose debugging information.

Problems/solutions encountered during platform installation

  • problem: in .m2/settings.xml I tried to use linux's ${HOME} variable to indicate the home on my machine for the 'jdbc.url' variable. This will cause a failure when executing ant db.init
    solution: don't use system variables. Even though the system variable was defined and could be seen by the system, you need to hard-code the absolute path for the jdbc.url var.
  • Don't forget to create the sail_database database and make sure your mysql server is up and running before you run ant db.init
  • You must make sure that your my.cnf file, which is a configuration file for MySQL contains the following content:
    [mysqld]
    lower_case_table_names=1
  • Don't forget to run "mvn resources:resources" followed by a refresh in eclipse before you deploy the application onto tomcat.
  • problem: When tomcat server is launched from within eclipse, you get an exception in the eclipse console view indicating that jdbc driver could not be found.
    solution: once the platform is in place, clean the project and build it. Then run 'mvn resources:resources" on the command line. Then deploy the project onto tomcat and then run pas-portal.
    note: running 'mvn resources:resources' is necessary (as mentioned in the notes above) because it will replace certain variables in the code, with their appropriate values.
  • No labels