eRoute JSF build stuff

Development Tools

SVN

svn://cixsvnuk.gsk.com/eRoute/trunk/eRoute 

Servers

• Development
  • http://stvsmlx011.corpnet2.com:8080/
• Test (Demo)
  • http://hlwus006.corpnet2.com:8080/eRoute
  • Location of the .ear file on the machine /proj/cix3/hlwus006/jboss-4.2.0.GA/server/default/deploy
• Production
  • http://hlwus013.corpnet2.com:28080/ (Note: Tomcat server.xml was changed to point to 28080 specifically)
  • Location of the .ear file on the machine /scratch/cix/jboss-4.2.0.GA/server/default/deploy

Techologies

• Apache MyFaces^? http://myfaces.apache.org/
• Java Persistence API (Hibernate implmentation) http://www.hibernate.org/

MyEclipse particulars

• Install your JBoss, and set to run on port 28080. Search in preferences for the JBoss 4.x server: Window|Preferences|myeclipse|Application servers|JBoss|JBoss 4.x. Set the home directory to C:\jboss-4.2.0.GA, leave server name as default, optional shutdown argument as --shutdown.
• Install EclEmma^? plugin.
• Install Subclipse plugin.
• We use JUnit 3.8, which is in the project.
• To redeploy:
  • Open the servers view. Right-click on the JBoss server, and choose Manage deployments|Add, then eRoute, with Exploded archive. This action will add eRoute to the Servers view, and will also carry out a deployment.
  • Redeploy by right-clicking on it and choosing 'redeploy'. This action copies the ear to the right place.
  • When redeploying in Development, JBoss doesn't always unpack the file. Therefore, after redeploying, edit the {JBoss}\server\default\deploy\eRoute.ear\META-INF\application.xml, and add and remove a space and save. This sequence forces JBoss to reload.

Links

• JSF kickstart tutorial http://www.exadel.com/tutorial/jsf/jsftutorial-kickstart.html
• JSF detailed tutorial http://www.coreservlets.com/JSF-Tutorial/
• Eclipse plugin for emma http://www.eclemma.org/
• http://mdritwiki.gsk.com/tw/bin/view/Cix/RogerPearseSERouteNotes Roger Pearse's eRoute notes
• TMA System

JBoss particulars

• version 4.2
  • Get the standard download from [ http://labs.jboss.com/jbossas/downloads ] (.zip), and unpack it to c:\jboss-4.2.0.GA.
• version 4.0.5GA. (No longer used)
  • For this version, you must get the version with EJB3. According to [http://labs.jboss.com/jbossas/downloads this], "If you want EJB3 ... support with JBoss AS 4.0.5, you MUST [http://labs.jboss.com/jemsinstaller/downloads/ download] and use the relevant version of JEMS Installer together with JDK5.0." This version is 1.2.0.GA. NB: It is best to run it from the website with Javaws. When the installer runs, install it to C:\jboss-4.0.5.GA (c:\program files\... will give an error when eRoute is deployed), select 'all', then 'standard'.
• [Do NOT install myfaces in 4.2.0GA.] Myfaces libraries upgrade: This version of jboss comes with an older (buggy) version of myfaces. To upgrade the libraries, compelte the following steps:
  1. Cix.Download myFaces libraries from http://myfaces.apache.org/  (version 1.1.5).
  2. Replace myfaces-api.jar, myfaces-impl.jar with myfaces-api-1.1.5.jar, myfaces-impl-1.1.5.jar @ <jboss-install>/server/<server-dir>/deploy/jbossweb-tomcat55.sar/jsf-libs (now jboss-web.deployer/jsf-libs in 4.2.0).
  3. Restart jboss.
• Secure access to the JMX console using username/password file as described here: http://www.jboss.org/wiki/Wiki.jsp?page=SecureTheJmxConsole.
• Add Oracle JDBC libraries ojdbc14.jar to <jboss-install>/server/<server-dir>/lib.
• Install the eRoute specific DataSource^? in JBoss:
  1. Go to the eRoute base directory.
  2. Copy /jboss-conf/deploy/eroute-ds.xml to <jboss-install>/server/<server-dir>/deploy.
  3. N.B. The eroute-ds.xml specifies the connection details for the test databases. Cix.Change the connection settings to point to production databases when deploying to production.
• On test and production servers, create and use $JBOSS_HOME/jbossStart.sh and $JBOSS_HOME/jbossStop.sh to start and stop JBoss server. The scripts set the JAVA_HOME and also bind JBoss to the server hostname (as opposed to localhost).

$JBOSS_HOME/jbossStart.sh:

#!/bin/sh

set -e
JAVA_HOME=/scratch/cix/jdk1.5.0_11
export JAVA_HOME

JBOSS_HOME=/scratch/cix/jboss-4.2.0.GA
export JBOSS_HOME

$JBOSS_HOME/bin/run.sh -b hlwus013.corpnet2.com
#nohup $JBOSS_HOME/bin/run.sh &

$JBOSS_HOME/jbossStop.sh:

#!/bin/sh

set -e

JAVA_HOME=/scratch/cix/jdk1.5.0_11
export JAVA_HOME

JBOSS_HOME=/scratch/cix/jboss-4.2.0.GA
export JBOSS_HOME

$JBOSS_HOME/bin/shutdown.sh -s hlwus013.corpnet2.com

These commands force the server to bind to the hostname, rather than to localhost, which is the default and, thus, is inaccessible anywhere except on the server itself.

Development environment only:

• Step required only in case you want to run selenium tests locally. You will need to alter the port for a development instance to 28080. This requirement is specified in server.xml in {jboss_root}/server/default/deploy/{tomcat}.sar (now {jboss_root}/server/default/deploy/jboss-web.deployer in 4.2.0):

<Connector port="28080" address="${jboss.bind.address}"

Production environment only:

• How http://eroute.gsk.com/ is mapped to http://hlwus013.corpnet2.com:28080/eRoute.
  1. Add DNS entry for eroute.gsk.com to point to hlwus013.corpnet2.com.
  2. Modify config (httpd.conf) of Apache server on http://hlwus013.corpnet2.com/ port 80 to specify how to forward requests from http://eroute.gsk.com/ to our Tomcat instance:
     • lines 1 to 12: A new virtual host is created and added to the Apache server running on http://hlwus013.corpnet2.com/ port 80.
     • lines 3 to 7: Specifies a docroot and allows anyone to access it.
     • lines 10: Use Rewriting rules to forward requests from http://eroute.gsk.com/eRoute to http://hlwus013.corpnet2.com:28080/eRoute.
     • lines 11: Use Rewriting rules to forward requests from http://eroute.gsk.com/ to http://hlwus013.corpnet2.com:28080/eRoute.

       1.  <VirtualHost *:80>
       2.    ServerName eroute.gsk.com
       3.    DocumentRoot /local/apps/pkg/pkgs/httpd-2.2.2/htdocs/eroute
       
       5.    <Directory />
       6.      Allow from all
       7.    </Directory>
        
       9.     RewriteEngine on
       10.   RewriteRule ^/eRoute(.*)$ http://hlwus013.corpnet2.com:28080/eRoute/$1 [P,L]
       11.   RewriteRule ^/(.*)$ http://hlwus013.corpnet2.com:28080/eRoute/$1 [P]
       12. </VirtualHost> 
             

  3. Configure the target Tomcat instance to instruct the application of the hostname and port number it needs to use when writing URL. Add proxyName and proxyPort to your Connector in server.xml.

              <Connector port="28080" [...] proxyName="eroute.gsk.com" proxyPort="80" />
          

Note on JBoss 4.2.0.GA and MyFaces^?

• JBoss Wiki entry
• JBoss 4.2 is not compatible with myfaces-api.jar and myfaces-impl.jar. If you have them, JBoss will complain and refer you to the JBoss Wiki above.
• The Wiki tells us to add the following to the web.xml. This action seems to allow us to run the project OK. Without these myfaces jars, we could not get the application to run.

<context-param>
     <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name>
     <param-value>true</param-value>
</context-param> 

Software Build Details

Build

• Deploy using MyEclipse
  1. Check out both "eRouteEar" and "eRouteWeb" together from SVN (see above URL).
  2. Create an Application Connector using MyEclipse^? to connect to the JBOSS server:
     • Prerequisite: (1) MyEclipse^? v5.x (2) JBOSS must have been installed; (3) a full jdk (not just jre) must have been installed.
     • Select Menu "Windows" > "Preferences", then expands "MyEclipse" > "Application Server"
     • Select "JBoss 4", and specify the location of your JBoss install. Enable the server.
     • Expand "JBoss 4", and specify the location of your full JDK.
     • Apply your changes.
  3. Your server should now be available in the "Servers" view. To show the view, use: "Windows" > "Show View" > "Others" > "MyEclipse Enterprise Workbench" > "Servers".
  4. Make sure MyEclipse^? won't deploy "test-lib" (libraries not to be deployed), as this may result in class conflict with JBoss's.
     • Go to Windows > Preferences > MyEclipse^? > J2EE Project > Web Projects
     • In the "Deployment" tab, uncheck all checkboxes for "Library Deployment Policies".
  5. Deploy the eRoute project.
     • In the "Servers" view, click the "Manager Deployments".
     • Select "JBoss 4" as the server to deploy to.
     • Add "eRoute" as the project you wish to deploy.
• Deploy using the build file.
  1. Check out the eRoute base directory from SVN (see above URL).
  2. Create JBOSS_HOME environment variable, and set it to where JBoss has been installed.
  3. Go to the eRoute base directory.
  4. Change the jboss.host and jboss.port properties in the build.properties file to match your JBoss server connection details. By default, these properties are set to localhost and 28080 (as these parameters are what is expected for the integration tests; see Cruise Control section).
  5. Run ant. This action will call the default redeploy target that will compile the code, create the .ear file, and deploy it to JBoss. N.B. JBoss will be started if it is not found to be running already on the hostname and port number configured in the build.properties.
  6. You should now be able to access the eRoute application.

• There are 2 lib folders:
  • eRouteWeb/test-lib: contains the lib only required by the JUnit tests or coverage report (not by the WebApp^?)
  • eRouteWeb/WebRoot/WEB-INF/lib: contains the lib required by the WebApp

Cruise Control

• JUnit Tests at http://hlwsalx003.corpnet2.com:8080/buildresults/eRoute:
  • Installed on hlwsalx003.corpnet2.com (Linux server) at /home/inforsen/cruisecontrol-bin-2.6.1
  • No scheduled runs; only when modifications are detected..
  • Email is sent when build fails or is fixed.
  • Calls coverage-report build target that runs unit-tests and builds coverage report.
  • Calls ear target when build is successful.
  • Publishes 2 artifacts:
    • Coverage report: Use coverage.html to access report.
    • eRoute.ear
• Integration Tests (i.e. Selenium tests) at http://hlwwd06d31591.sbphrd.corpnet1.com:8080/buildresults/eRoute:
  • Prerequisite:
    • Selenium server should be started on port 5444.
  • Installed on hlwwd06d31591.sbphrd.corpnet1.com (Windows server) at C:\cruisecontrol-bin-2.4.1.
  • Scheduled to run at 7 a.m. and 4 p.m. every day.
  • Email is sent when build fails or is fixed.
  • Calls integration-test build target that deploys the latest ear to JBOSS. N.B. JBoss will be started if it is not found to be running already on the hostname and port number configured in the build.properties.
  • Publishes the JUnit test report as an artifact.

Selenium

Run Selenium Locally
If you wish to run your test locally, then you need to start a selenium server beforehand:

• Make sure the com.gsk.cix.selenium.ERouteSelTestCase points to the right JBoss server (see DEFAULT_BASE_URL). By default, the base class expects the WebApp to be available at localhost:28080 and the Selenium server running on port 5444:
• Download the Selenium Core from http://www.openqa.org/selenium-core.
• Download the Selenium Remote Control from http://www.openqa.org/selenium-rc. Version from 0.9.1 (even if SNAPSHOT) is required if you want to launch some tests in Firefox 2.0.
• Unzip the content of both zip files in the same root directory, i.e., c:/selenium.
• In the selenium\server directory, start selenium server on port 5444 using following commands:

  java -jar selenium-server.jar -port 5444

  or

  java -jar c:\selenium\server\selenium-server.jar -port 5444

Test Data
Selenium relies on test data held in the database (i.e., project codes, routing information). The tests use a test user which mudid is "uxx20597" to perform add/remove/update operations on routes for a given set of project codes. The tests expects to find the routes of a given project in a specific state, otherwise they fail.

In order for the integration tests to complete successfully, we need to make sure that:

• Test User is a custodian of project codes "3196" and "1222".
• Test User has "read only" access to project code "16517".
• Project Codes "3196" and "16157" are active.
• Project Code "93" is not active.
• Project Code "3196" has no route associated with it.
• Project Code "1222" is active but has no STS protocol associated with it.