This Document Is Meant for the DEVELOPER

This document is meant for the DEVELOPER

0. Get install-files from the opus college website

All (or most) install-files in this document can be fetched from the opus college website:

Go to the menu: SUPPORT

Also update-files in the future can be fetched from this website.

1. Server Admin package

Start with following all instructions and installations in the server_admin-directory (server_admins_V1.0). After that you will have opusCollege fully deployed, together with the right JDK, Tomcat 5.5 and PostgreSQL 8.2 and the filled opusCollege database.

2. Install Ant

1. Get the last version of "ant" on site:
2. Extract the files in c:\Java folder, like with the opusCollege-environment installation.

3. Environment variables

Set ANT_HOME in the environment variables to the root directory of your ant-distribution

Set CATALINA_HOME in the environment variables to the root directory of your apache-tomcat-version.

(for Linux) Add $ANT_HOME/bin inside the "path" variable.

4. Eclipse – installation and working with it

4.1.Install Eclipse

Go to:

Used version: Ganymede

With a.o.:

Eclipse

WTP

Install the application.

When you open eclipse the first time you have to create a workspace. At UCI we use: E:/workspace_opus_svn.

4.2.Eclipse - Plugins

For all plugins:

1. Open Eclipse. Go to Help -> Software Updates -> Find and Install.
2. Select "Search for new features to install". Click "Next".
3. Click "New Remote Site".

Spring IDE update site:

Remark: some parts are outdated. De-select them.

JasperForge.org update site:

-> NOTE: this update site doesn’t exist anymore. And no alternative can be found…

JSEclipse:

Eclipse Checkstyle update site:

Activate the stylechecker for your project

Go to window -> preferences -> checkstyle

Choose new ->

Type: project relative configuration

Name: Opus Checkstyle’

Location: browse to the college project-root and then to checkstyle/sun_checks_eclipse_uci.xml

Set this as a default. Set it as default.

Then go to the project-root, right click and choose Checkstyle -> ‘activate checkstyle’

Subclipse update site:

With Subclipse you install the Subversion Client, but also do install the SVNKit.

SVNKit can be used instead of JavaHL and seems to be available in Eclipse right away. SVNKit is a Java implementation and avoids the many possible problems with subversion installations at clients.

To use this, go to Window -> Preferences -> Team -> SVN -> SVN Interface and change JavaHL to SVNKit (Pure Java)

Trac plugin:

First of all you need to install the Trac plugins that you can find here:

Download TracRpcExt, along with the original XmlRpcPlugin

Trac update-site:

4.3.Eclipse – Configuration changes

To make outgoing changes for the version control system more visible, change the following property:

Window / preferences / Team / SVN / Label Decorations / Icon Decorations: check the Outgoing Changes.

To make tabs-behaviour of Eclipse for all participants the same, change the following properties:

Window / preferences / General / editors / texteditor -> check ‘insert spaces for tabs’.

Window / preferences / Java / Code Style / Formatter -> change the Tab policy to ‘Spaces Only’. Indentation Size and Tab Size both have to be 4. Change the name of the Profile to Eclipse Opus and save. It will now be used.

To make sure that your projects are refreshed each time add the following to your preferences:

Window / preferences / General / Workspace -> check ‘refresh automatically’.

4.4. Eclipse - Runtime JDK 1.6.0 installation

Start Eclipse.

To compile Java 5 projects properly, you need to tell Eclipse about our 1.6.0 JDK:

• Start Eclipse.
• Open Windows -> Preferences and then select Java -> Installed JREs
  
• Click Add...
• Select the home directory of your JDK 1.6.0 installation (not the JRE) and set the JRE name to jdk1.6.0
  
• Click OK.

4.5.Eclipse - Set your workspace as a variable

Go inside Eclipse to window -> preferences -> general -> workspace -> Linked resources

Create a new variable WORKSPACE with a link to your eclipse-workspace. You can now add relative links to your projects. This will be necessary for the future modularization of the project.

4.6.Eclipse – Add Tomcat 6.0 as a server runtime.

You have to add Tomcat56.0 as a server runtime to your workspace first.

Choose New Server -> point to the root of your tomcat 6.0 installation. Set this as your system JRE default.

4.7.1. Eclipse - TRAC

Connect to url:

4.7.2. Eclipse – Subversion -Import the projects

Import the code for the projects college, eSURA, and all modules through Subversionintothe workspace of Eclipse.

Choose Import -> checkout projects from SVN.

Connect to url:

You have got your own user/password combination. Use this to log on to the SVN-server.

Note: if something goes wrong with your user or password, you can delete the entire password-storage for svn on your filesystem and try again;

Windows: C:/Documents and Settings/<user>/ApplicationData/Subverson/auth

Linux: ~/.subversion/auth

Also see:

You see a structure as follows:

-branches

-tags

-trunk

Choose trunk. You can now import all projects separately into your workspace.

After importing the projects the java build path and libraries and dependencies of your projects are not yet correct. Do the following for each project. Go to properties. Choose Java Build Path:

1. College (Core module)

-Tab Source

Delete the default src-folder and choose add folder. You have to select src/main/java and src/test/java. Change the buildpath (below in the popup screen) from java\bin to java/build/classes

-Tab Projects

Do nothing.

-Tab Libraries

Add a reference to the college Web App Library (Add Library -> Web App Libraries -> ‘college’)

Choose Tomcat 6.0 as targeted server runtime.

Add a reference to JUnit4

-Tab Order and Export

Do nothing.

2. eSURA (target project)

-Tab Source

Delete the src-folder mentioned and choose add folder. You have to select src/main/java. Change the buildpath from java\bin to java/build (Note: WITHOUT classes as in the modules !!)

-Tab Libraries

Add a reference to the eSURA Web App Library (Add Library -> Web App Libraries -> ‘eSURA)

Choose Tomcat 6.0 as targeted server runtime.

Furthermore do nothing (it uses it’s own copied classes and libraries !!)

3. All modules

-Tab Source

Delete the src-folder mentioned and choose add folder. You have to select src/main/java and src/test/java. Change the buildpath from java\bin to java/build/classes

-Tab Projects

Add dependency on the core module (college)

-Tab Libraries

Add college/build/classes as a class folder

Add a reference to the college Web App Library (Add Library -> Web App Libraries -> ‘college’)

Choose Tomcat 6.0 as targeted server runtime.

Add a reference to JUnit4

4. College module –Country / language specific settings

In /college/webapp/WEB-INF/web.xml there are some country specific settings (a.o. language, nationality). Adjust them to your own country specific needs.

In /college/webapp/WEB-INF/modules/college/web-context.xml there is a localeResolver, of which the defaultLocale value has to be set. You have to adjust this defaultLocale to your country’s needs.

Besides that you have to adjust the locale in /college/webapp/WEB-INF/login.jsp to your country’s needs.

5. Target-project eSURA - Additional

Create a directory ‘dist’ in the root of the eSURA-project

Copy the following files and rename them:

eSURA:src/main/java/log4j.properties.template -> log4j.properties

college:main/webapp/META-INF/context.xml.template -> context.xml (not necessary anymore)

college:main/webapp/WEB-INF/jdbc.properties.template -> jdbc.properties (not necessary anymore)

To test if everything is working, run the build.xml of the Core (= college ). You do this as follows: go to /eSURA/applications/college. You run the ‘all’ target of the build.xml.

eSURA is the target-project where you build your application. You can choose there (directory applications) if you only want to build college, or college together with fee, or college together with scholarship, and so on…

In the eSURA project you have a directory /lib. You may not delete this directory, because it is used by Ant for building.

The .settings directory is also copied through SVN. Therefore your projects are already web-projects. The only file of the .settings directory that is in SVN but should be modified through the project preferences is: org.eclipse.jst.common.project.facet.core.prefs. In there are local values.

Note: default you have write access on report, NOT on the other modules. If you need specific access, contact Monique in het Veld or Janneke Nooitgedagt at the RadboudUniversity, Nijmegen, Netherlands.

Close Eclipse and restart. Now the First real build of the projects will be done, including all libraries, that are part of the projects.

4.8. Eclipse - Configure the database connection

a) Rename college/src/main/webapp/META-INF/context.xml.template to college/src/main/webapp/META-INF/context.xml (or make a copy with this name).

Then edit web/META-INF/context.xml and change JDBC connection information according to your database server. Example:

<Resource

name="opusCollegeDS"

auth="Container"

type="javax.sql.DataSource"

driverClassName="org.postgresql.Driver"

url="jdbc:postgresql://opusdb:5432/opusCollege"

username="postgres"

password="123koffie"

maxActive="20"

maxIdle="10"

maxWait="-1"

removeAbandoned="true"

removeAbandonedTimeout="60"

/>

Edit url, username and password accordingly to your PostgreSQL installation.

c) Rename college/src/main/webapp/WEB-INF/jdbc.properties.template to college/src/main/webapp/jdbc.properties (or make a copy with this name). Then edit the file accordingly to your database connection settings.

d) Rename eSURA/src/main/java/log4j.properties.template to eSURA/src/main/java/log4j.properties (or make a copy with this name). Then edit the file according to your desired logging wishes (debug / info).

4.9. Eclipse – Understanding and working with the modular structure of the projects

With OpusCollege we’re waiting for Spring Dynamic Modules to make the project truly modular and fit for OSGi. At the moment we have already taken a few steps in that direction.

Start with structuring the application through several projects (modules): first onesare Fees, Report and Scholarship module

Bind the projects together with Ant -> one WAR-file

The structure is as follows:

Several projects:

1 or more modules: fee, scholarship, report

1 core-project: college with all libraries

1 target-project: eSURA

All projects have their own build.xml

Module-project:

Default structure (maven-based):

Src/main/java

Src/test/java

Src/main/webapp/WEB-INF/modules/module-name

Src/main/webapp/WEB-INF/views/module-name

Has own configuration files:

Org.uci.opus.module-name/application.xml (context)

Org.uci.opus.module-name/messages.properties

Src/main/webapp/META-INF/MANIFEST.MF

Src/main/webapp/WEB-INF/modules/module-name/web-context.xml (applicationContext)

Eclipse build path: Dependency towards core project

Core-project:

Has everything a module-project has

Note: web-context.xml has some extra’s:

InternalResourceViewResolver

Interceptors: ModuleInterceptor

ModuleMessagesRegistrar

Extra (1):

webapp/WEB-INF/web.xml

With dispatcher-servlet: eSURA

webapp/WEB-INF/jdbc.properties

webapp/index.html

org.uci.opus.college.module package:

Number of modules is counted dynamically and used throughout the application: see Module and ModuleInterceptor

Messages.properties files of core and modules are gathered together: see ModuleMessagesRegistrar

Target project:

Nearly empty project, only with:

Applications-directory: here you specify the application you want (with one or more modules). Every application has it’s own build.xml, that uses common-build/application-targets.xml

Common-build-directory: here you specify the actions you have to perform for each application:

application-targets.xml: Clean target-project, copy application-files, compile

web-targets.xml: Create war-file into dist-directory

If you want to deploy the application with one or more modules you do as follows:

Use “ant” to create the application. There are a number of build-files created in /eSURA/applications. You can choose which of the build-files you will run. The default value for the build-files is ‘all’. If you use this, the selected modules will clean-up themselves, perform a build (locally in their own build-directory) and then copy themselves into the eSURA -project, together with their web-artifacts.

After you have run the build-script you must refresh the eSURA-project, before you can either run the application internally or create a war-file externally. The modules you select will be shown in the menu on top, the others will not be visible and reachable:

• If you want to run on the internal Tomcat you can just refresh your ‘eSURA’ project and then run it on the internal server.
• After creation you can create a war-file through /eSURA/common-build/web-targets.xml. It will create a war-file in the eSURA /dist directory. You can deploy it to an external tomcat server.

Note: in the internal server of eclipse you keep seeing a module once you have loaded it. This is a bug from eclipse. Cleaning the projects regularly will help preventing this. When you deploy a war-file of the application to an external tomcat webserver you do not have this problem.

Note: Furthermore you cannot see all the reports correctly in the internal server. When you deploy a war-file of the application to an external tomcat webserver you do not have this problem.

Note: you might have to configure the database settings. Look in the following files in the eSURA-project for this:

WEB-INF/jdbc.properties

META-INF/context.xml

Note: you might have to configure the log-settings. In eSURA/src/main/java/log4j.properties you can decide to put the logging on debug or warn (default is debug).

This file will be copied by ant into:

/{targetproject-name}/src/main/webapp/WEB-INF/classes

If you need messages.properties files that are in the login-page (before you are logged in), you have to paste the tags in the special messages.properties files you can find in the target-project under:

/{targetproject-name}/src/main/java

They will be copied by ant into:

/{targetproject-name}/src/main/webapp/WEB-INF/classes

4.10. Debugging within Eclipse

Debugging in Eclipse is rather easy. You have to use your internal server to be able to use this feature. Instead of ‘Run on server’ you now choose ‘Debug on server’.

This is possible because in our ant-build we have chosen as a compile option:

<javac destdir="${main.classes.dir}" debug="true">

Therefore Eclipse can use the class-files for debugging and does not need the source-files in the target-project.

You can create breakpoints by double clicking the source files in the source projects (e.g. college, fee, report, scholarship, …) in the left gutter of your editor. The application can be built and started and will stop at this breakpoint. Then you can step in / step over / step out of the method at this breakpoint. You can also explore the status of variables at that point in the application. For this you can use ‘Inspect’. You simply select the expression you wish to see the values of and then right-click and select ‘inspect’.

If you wish to ‘watch’ variables, you do not have access to at a specific breakpoint you can add them through the ‘watch expressions’. You can now view these variables at every stage in the debug mode.

You can even debug 3rd party libraries if you download the source (like spring) and tell Eclipse where to find the source. This can be done in project properties => Java build path => libraries => e. g.Web app libraries => open/extend the library and edit the source attachment. You can find a few 3rd party libraries in /college/doc/sources/.

4.11. Eclipse - Create the application as a war-file

If you work with the sources of eSURA, you can choose between different options to deploy the application:

1. create a war-file from the sources through the eclipse export-function. You can deploy the war-file in a tomcat 5.5 server, in the apache-tomcat/server/webapps directory.
2. create a war-file through /eSURA /common-build/webtargets.xml. Here you create a war-file in the directory /eSURA /dist.You can deploy the war-file in a tomcat 5.5 server, in the apache-tomcat/server/webapps directory.

4.12. Running the application within Eclipse