note
Version: 3.1 2010-03-23
Subject
Install Manual Developers opusCollege - WINDOWS
To
Developers Local Compentence Center
CC
opus User Group
From
Monique in het Veld
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:
http://www.opuscollege.net/
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: http://ant.apache.org/
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-tomcatversion.
(for Linux) Add $ANT_HOME/bin inside the "path" variable.
4. Eclipse – installation and working with it
4.1. Install Eclipse
Go to: http://www.eclipse.org/downloads/
Used version: Ganymede
With a.o.:
Eclipse
InstallManual_Opus-College_development.doc
Pagina 1 van
InstallManual_Opus-College_development
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: http://springide.org/updatesite/
Remark: some parts are outdated. De-select them.
JasperForge.org update site: http://www.jasperforge.org/update
-> NOTE: this update site doesn’t exist anymore. And no alternative can be found…
JSEclipse: http://download.macromedia.com/pub/labs/jseclipse/autoinstall/
Eclipse Checkstyle update site: http://eclipse-cs.sourceforge.net/update
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: http://subclipse.tigris.org/update_1.6.x
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: http://trachacks.org/wiki/EclipseTracPlugin
Download TracRpcExt, along with the original XmlRpcPlugin
Trac update-site: http://trac-hacks.org/svn/eclipsetracplugin/eclipse/update/
InstallManual_Opus-College_development.doc
Pagina 2 van
InstallManual_Opus-College_development
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
InstallManual_Opus-College_development.doc
Pagina 3 van
InstallManual_Opus-College_development
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:
http://www.opuscollege.net/trac/opus/
4.7.2. Eclipse – Subversion - Import the projects
Import the code for the projects college, eSURA, and all modules through Subversion into the
workspace of Eclipse.
Choose Import -> checkout projects from SVN.
Connect to url:
http://www.opuscollege.net/svn/opus
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 passwordstorage for svn on your filesystem and try again;
Windows: C:/Documents and Settings/<user>/ApplicationData/Subverson/auth
Linux: ~/.subversion/auth
Also see: http://subclipse.tigris.org/wiki/PluginFAQ
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’)
InstallManual_Opus-College_development.doc
Pagina 4 van
InstallManual_Opus-College_development
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:
anymore)
main/webapp/META-INF/context.xml.template -> context.xml (not necessary
college:
main/webapp/WEB-INF/jdbc.properties.template -> jdbc.properties (not necessary
anymore)
InstallManual_Opus-College_development.doc
Pagina 5 van
InstallManual_Opus-College_development
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 webprojects. 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 Radboud University, 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.
InstallManual_Opus-College_development.doc
Pagina 6 van
InstallManual_Opus-College_development
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 ones
are 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
InstallManual_Opus-College_development.doc
Pagina 7 van
InstallManual_Opus-College_development

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 warfile 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 eSURAproject for this:
WEB-INF/jdbc.properties
META-INF/context.xml
InstallManual_Opus-College_development.doc
Pagina 8 van
InstallManual_Opus-College_development
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 rightclick 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 warfile 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
You need a server configuration in able to run the application directly from Eclipse. You can point
to the installed server runtime (Tomcat server) for this.
InstallManual_Opus-College_development.doc
Pagina 9 van
InstallManual_Opus-College_development
Note: you have to alter the launch configuration properties:
- Open the tab Arguments and set the working directory to the bin of your webserver (e.g.
D:/java/apache-tomcat-5.5.23/bin)
- Open the tab Classpath and at rt.jar to your user entries. You can find this library under the javajdk-folder: jre\lib.
5. iReport – installation and working with it
5.1. Install iReport
1. Get the last version of “iReport” on site: http://www.jasperforge.org/sf/projects/ireport.
Version 3.0.0 is in the installation package.
2. Extract the files in c:\Java folder, like with the opusCollege-environment installation.
3. (for Linux) Open the command prompt and type the home directory of iReport (Example: cd
c:\Java\iReport-3.0.0-src\iReport-3.0.0-src). Then type "ant". The system will now create
some important files.
4. (for Linux) Copy the file Tools.jar from jdk\lib directory and paste in ireport\lib directory
5. Put the Postgres library into the iReport\lib directory
6. Put the report templates from /college/WEB-INF/reports/templates into the templates
directory of iReport.
7. Execute the file iReport.bat OR the iReport.exe in the iReport directory root.
8. Set the output folder (options / compile) to the java/eclipse environment: /reports/web/WEBINF/reports.
9. Do not create .bak-files (options / backup)
10. Open and execute the file basic_report_opuscollege.jrxml (see directory /reports/WEBINF/reports). This is an example.
11. Click on Data menu, Connections/Data Sources, after click on new and select a JDBC
connection.
12. Put the follow settings:
a. JDBC Driver: org.postgresql.Driver
b. JDBC Url: jdbc:postgresql://localhost:5432/opuscollege
c. User Name: postgres
d. Password: 123koffie
13. Click on test button and see if the datasource works
For working with iBatis SQLmaps within iReport you have to take some extra actions:
1. Put the classes-directory of the eSURA target-project on the classpath: choose menu ->
options -> classpath and browse to /eSURA/src/main/webapp/WEB-INF/classes. This is
the location where the classes of the core project and all modules will be copied to through
ant-build.
2. Use for your queries the JavaBeanDataSource instead of the sql-datasource you created
above.
5.2. Link OpusCollege layout templates in iReport
In the directory web/WEB-INF/reports/templates of the opusCollege eclipse project you find two
templates for the opusCollege reports: A normal and a landscape variation. Copy these two files
InstallManual_Opus-College_development.doc
Pagina 10 van
InstallManual_Opus-College_development
into your iReport-installation directory, in the folder ‘templates’. The next time you start iReport you
will have access to these templates.
5.3. Create a report in iReport
1. Choose ‘Report wizard’ from the menu and follow the steps:
a. Make a query (without parameters !!)
b. Choose the fields to show in the report
c. Make (optionally) one or more group by’s
d. Choose the layout (note: there is a a opusCollege layout in the near future here to
choose)
2. You now see a report, but without fields except the first one. You have to follow the next
steps:
a. Shift the vertical border of the label-fields to the right, because they overlap
b. Choose a different font. You will now see all the fields selected
3. Compile the report through the menu. Correct errors if there are any until you get a clean
compile.
4. If you want to have parameters in your query, you can now add them through the menu
‘parameters’.
a. Create a parameter name (whereClause. Make this a string, since all parameters
from the webpage will be bundled in to this whereClause. Give it a default value “”;
b. Go to the query. You can add your parameter into the query as follows:
select organizationalUnit.organizationalUnitDescription,
study.studydescription,
person.surnamefull, person.firstnamesfull, person.genderCode,
person.provinceOfOriginCode
from opusCollege.student, opusCollege.person, opusCollege.study,
opusCollege.organizationalUnit,
opusCollege.studyGradeType, opusCollege.studyYear
where student.personId = person.id
and student.primaryStudyId = study.id
and study.organizationalUnitId = organizationalUnit.id
and studyGradeType.studyId = study.id
and studyYear.studyGradeTypeId = studyGradeType.id
$P!{whereClause}
c.
Go to the webpage. You can build the query by using (one or more times):
‘&&where.paramname.id=${paramnameValue}
5. Save the compiled report (extension .jasper) to the reports-directory of the project or send
it to the application administrator to add it for you (e-mail: m.inhetveld@uci.ru.nl)
6. If you have the authorization, you can now make links for PDF/HTML/EXCEL in the
project-jsp that belongs to the query (usually this will be: reportoverview.jsp). These links
looks something like this when you have no parameters in the report (where student2 is
replaced with the name of your report):
<a href="/eSURA/reports.view?name=student2.pdf"
target="otherwindow">PDF</a>
<a href="/eSURA/reports.view?name=student2.html"
target="otherwindow">HMTL</a>
InstallManual_Opus-College_development.doc
Pagina 11 van
InstallManual_Opus-College_development
<a href="/eSURA/reports.view?name=student2.xls">Excel</a>
If you have one parameter the links will look something lilke this (where student2 is
replaced with the name of your report)
<a
href="/eSURA/reports.view?name=student2.pdf&where.student.studentId=${pa
ram1value}" target="otherwindow">PDF</a>
<a
href="/eSURA/reports.view?name=student2.html&where.student.studentId=${p
aram1value}" target="otherwindow">HMTL</a>
<a
href="/eSURA/reports.view?name=student2.xls&where.student.studentId==${p
aram1value}” target="otherwindow">Excel</a>
6. Renaming the target-project (opus -> eSURA -> ???)
If you wish to create a new target-project with another name (for instance, now the application is
called ‘eSURA’ instead of 'opus', you have to perform the following actions:
1. copy the targetproject to a project with the new name
1. college/WEB-INF/web.xml: rename display-name and dispatcherservlet from <old name> to
<new name>.
3. adjust college/common-build/compile-targets.xml -> <property name="targetproject.dir"
value="${basedir}/../<old name>"/> -> <property name="targetproject.dir" value="${basedir}/../<new
name>"/>
4. adjust applicationContext-module.xml in all projects:
<property name="startPage" value="/<old name>/college/index.html"/> ->
<property name="startPage" value="/<new name>/college/index.html"/>
5. LoginController -> change redirect-dir from <old name> to <new name>
6. LogoutController -> change redirect-dir from <old name> to <new name>
7. login.jsp, loginError.jsp -> change name in <title></title>
Then in Eclipse you have to change a few things on your project build path:
1. output folders: /build (instead of bin)
2. src folders: src/main/java (instead of src)
InstallManual_Opus-College_development.doc
Pagina 12 van
InstallManual_Opus-College_development