note
Version: 3 2008-04-01
Subject
Install Manual Developers opusCollege - WINDOWS
To
Error! Not a valid bookmark self-reference.
CC
opus User Group
Error! Not a valid
From
bookmark selfreference.
[date]
[doccodeuci]
Error! Not a valid
bookmark selfreference.
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.
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 1 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
4. Eclipse – installation and working with it
4.1. Install Eclipse 3.3.3 with WTP 2.0
Go to: http://www.eclipse.org/downloads/
Used version: winter 2007
With a.o.:
Eclipse 3.3
WTP 2.0
Install the application.
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’
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 2 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
To make outgoing changes for the version control system more visible, change the following
property:
CVS: Window / preferences / Team / CVS / 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.3. Eclipse - Runtime JDK 1.5.0 installation
Start Eclipse.
To compile Java 5 projects properly, you need to tell Eclipse about our 1.5.0 JDK:


Open Windows -> Preferences and then select Java -> Installed JREs


Start Eclipse.
Click Add...
Select the home directory of your JDK 1.5.0 installation (not the JRE) and set the JRE name
to jdk1.5.0
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 3 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS

Click OK.
4.4. 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.5. Eclipse - Import the projects
Import the code for the projects college, eSURA, fee and scholarship through Subversion into the
workspace of Eclipse. Create a new workspace for this.
Connect to:
Url:
http://snuitvlieg.uci.ru.nl/svn/opus
You have got your own user/password combination. Use this to log on to the SVN-server.
You can now choose to get existing modules inside your eclipse environment: choose import
existing modules into the workspace.
If you have not added Tomcat5.5 to your project, then do this now: choose tomcat 5.5 as targeted
runtime in your project properties.
Then you have to manually add some dependencies to the eclipse-projects:
- All src and test directories have to be altered:
i. Core & modules: src/main/java
ii. Core & modules: src/test/java
-> output folder <project>/build/classes
iii. eSURA: src/main/java -> output folder eSURA/build/
-
all modules (fee, report, scholarship) have to have a dependency on the core module
-
(college) in properties / java build path / projects
all modules and the core have to have a reference to the college web app library in
properties / java build path / libraries (Mark: eSURA must not have this, it uses it’s own
copied classes and libraries !!):
Properties  Libraries  Add Library  Web App Libraries  next  Project = core
-
(= college)  Finish
all modules have to have college/build/classes as a class folder in properties / java
build path / libraries (Mark: eSURA must not have this, it uses it’s own copied classes
and libraries !!)
-
Make sure you include the internal server environment (apache tomcat 5.5) into the
-
runtime environment of each project. (Properties  Targeted Runtimes)
Add the apache tomcat 5.5 runtime to your project-libraries in properties / java build
path / libraries (for the right servlet-api.jar). If you do this you will automatically achieve
the right tomcat libraries you need for compilation (Catalina.jar and servlet-apixxx.jar).
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 4 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
-
all projects have to have a reference to JUnit4 in properties / java build path / libraries
(for the right junit.jar)
create a directory ‘dist’ in the root of the eSURA-project
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: you have write access on eSURA, fee and scholarship, NOT on college.
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.6. 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://localhost:5432/opusCollege"
username="postgres"
password="123koffie"
maxActive="20"
maxIdle="10"
maxWait="-1"
removeAbandoned="true"
removeAbandonedTimeout="60"
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 5 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
/>
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.7. 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:
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 6 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
 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.
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 7 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS

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
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.8. 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
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 8 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
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.9. 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.10. 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.
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.
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 9 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
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
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 !!)
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 10 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
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>
<a href="/eSURA/reports.view?name=student2.xls">Excel</a>
InstallManual_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 11 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS
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_Developers_WINDOWS.doc
Erro
r!
Refe
renc
e
Pagina 12 van
sour
ce
not
foun
d.
InstallManual_Developers_WINDOWS