Subject / Install Manual Developers opusCollege - WINDOWS
To / DevelopersLocalCompentenceCenter
CC / opus User Group
From / Monique in het Veld
InstallManual_Opus-College_development.doc / Pagina 1 van / InstallManual_Opus-College_development
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
- Get the last version of "ant" on site:
- 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:
- Open Eclipse. Go to Help -> Software Updates -> Find and Install.
- Select "Search for new features to install". Click "Next".
- 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:
- 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.
- 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