Warning
Recent change in Eclipse setup
Due to its unreliability, we have recently stopped relying on the Maven plugin for Eclipse to manage the project build path. Instead, we are using the eclipse:eclipse plugin for Maven to generate a static build path. Please note the changes in the Eclipse project setup.
This document describes how to set up an Eclipse environment for running Rice from source and/or for developing on the Kuali Rice project. To create your own Kuali Rice client application, see the instructions in Creating a Rice-Enabled Application.
Install Java 5 SDK - http://java.sun.com.
Install the Eclipse Europa Bundle for Java Developers - http://www.eclipse.org/europa/
You need to allocate at least 768MB of memory for the Eclipse runtime and at least 512MB of memory for the JVM that Eclipse uses when it runs Java programs and commands.
Go to Eclipse Preferences.
On Windows: Window --> Preferences --> Java --> Installed JREs.
On Mac OS X: Eclipse --> Preferences --> Java --> Installed JREs.
Select the JRE and click Edit.
Add -Xmx768m to Default VM Arguments
Install Maven2 for command line usage:
Download Maven2.0.9 from http://maven.apache.org/download.html.
Install Maven2 into C:\maven on Windows or /opt/maven on Linux. This directory is called the Maven Root directory.
Register Maven on your computer's PATH so that it can be invoked as an executable without have to run the mvn command from the <maven_root>/bin directory all of the time.
Set the M2_HOME environment variable on your system to the location of your Maven2 installation.
Update .m2 repository directory (WINDOWS ONLY) By default (on Windows) maven places the .m2 repo directory in the user directory inside the Documents and Settings folder. The space characters can cause issues. To avoid them we need to do the following:
Figure out where you want your local maven repository to be stored, i.e. C:\work\m2
Make sure you turn off eclipse if it has auto updating maven turned on.
Move everything from your old maven directory to your new one. This will save you a considerable amount of time. If you do not do this then maven will re-download all repositories to the new location.
Update your settings.xml file. This should be located in C:\Documents and Settings\user\.m2\settings.xml. Add this line to the file somewhere inside the <settings> tag:
<localRepository>C:\work\m2</localRepository>
Note: You only need to follow these instructions if you downloaded the source distribution of Rice as a zip file. If you are a contributing developer who will be committing code to CVS, please skip this step (Importing rice into Eclipse as a Project) and go to the next one instead.
Open Eclipse.
Choose File --> Import --> Existing Projects into Workspace.
Browse for and select /java/projects/rice (or where ever you unzipped the source distribution to) as the root project directory and click Finish.
Note: You do not need to perform the steps in this section if you have downloaded the source distribution of Rice as a zip file.
We recommend installing Subclipse as a plugin from your Eclipse instance (http://subclipse.tigris.org/install.html)
Set up a new SVN repository in Eclipse: https://test.kuali.org/svn/rice
Check out the Rice code from the appropriate branch of code (i.e. branches/rice-release-1-0-0-br)
If this is the first time you've set up Eclipse to work with Rice, Maven won't find the Oracle drivers in the Kuali repository.
If you do not already have an Oracle driver saved in /java/drivers as ojdbc14.jar, you can download one from http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html. Save it as /java/drivers/ojdbc14.jar
Run this command from the command line (this should all be on one line when you enter it):
UNIX
mvn install:install-file -DgroupId=com.oracle -DartifactId=ojdbc14 -Dversion=10.2.0.3.0 -Dpackaging=jar -Dfile=/java/drivers/ojdbc14.jar
Windows
mvn install:install-file -DgroupId=com.oracle -DartifactId=ojdbc14 -Dversion=10.2.0.3.0 -Dpackaging=jar -Dfile=c:/java/drivers/ojdbc14.jar
Or, run the equivalent Ant target:
ant install-oracle-jar
The driver for MySQL is already referenced by the Kuali Rice project. Rice does not have out-of-the-box support for other RDBMS at this point in time. However, if you want to use other databases, it is possible to add database support for that particular database as long as it’s supported by the Apache OJB project (http://db.apache.org/ojb).
If this is the first time you are using Eclipse with a project build path generated by the eclipse:eclipse Maven plugin, you need to define the M2_REPO Classpath Variable in your Eclipse: Java > Build Path > Classpath Variable, under the Preferences menu.
The Rice project contains auto-generated build path entries that rely on the presence of this M2_REPO variable to determine the location of dependency libraries.
If dependency libraries have been added or removed from the Rice project, including the first time you check out Rice, you should run the retrieve-maven-dependencies Ant target to pull down all necessary libraries.
Note: For the Maven2 Ant tasks to work, Ant has to know where your Maven2 home is. If you have set the M2_HOME variable in your system environment, it will be recognized automatically. If not, or if for some reason you want to use a different location (e.g., if you want to have multiple Maven installations), then you can set the maven.home.directory property in /home/ubuntu/kuali-build.properties.
Add the build.xml file in the root of the Rice project to your Ant view, or open a shell to the Rice project directory and run the retrieve-maven-dependencies target. You should see Maven retrieving any required dependencies. If you are running this Ant task in Eclipse, then you must recognize the PATH environment variable under Run > External Tools > Open External Tools Dialog > Environment.
Optionally, if you have trouble running this Ant target, you can just run an mvn compile from the command line to invoke a Maven compilation. This will download all dependencies into your local maven repository.
Execute a clean build of the project in Eclipse:
If your build was previously broken due to the M2_REPO classpath variable being undefined or due to missing libraries, it should now have been built successfully.
To set up the database, please follow the instructions in the Installation Guide under Preparing the Database.
Note: Be sure to use an appropriate editor such as vi or Notepad when editing configuration files. For example, we have found that WordPad can corrupt the configuration file.
To install the configuration file for the Kuali Rice sample application, you can do an Ant-based setup or a manual setup.
Execute the prepare-dev-environment Ant target in the build.xml file located in the root of the project.
This creates: <user home>/kuali/main/dev/sample-app-config.xml
Copy the config/templates/sample-app-config.template.xml file to <user home>/kuali/main/dev/sample-app-config.xml.
For Windows, your user home is: C:\Documents and Settings\<user name>
For Unix/Linux, your user home is: /home/<user name>
For Mac OS X, your user home is: /Users/<user name>
Add the appropriate database parameters to <user home>/kuali/main/dev/sample-app-config.xml
Oracle
<param name="datasource.url">jdbc:oracle:thin:@localhost:1521:XE</param> <param name="datasource.username">oracle.username</param> <param name="datasource.password">oracle.password</param>
MySQL
<param name="datasource.url">jdbc:mysql://localhost:3306/kulrice</param> <param name="datasource.username">mysql.username</param> <param name="datasource.password">mysql.password</param>
Back in Eclipse, locate and run the rice - JettyServer.launch file:
Point your browser to the following url: http://localhost:8080/kr-dev
If you change any of the dependencies in any of the Rice pom.xml files, you must run the update-eclipse-classpath Ant target to regenerate the top-level Eclipse .classpath file for the project.
If you change the dependencies and commit the change, when others update their local source copy they must run the corresponding retrieve-maven-dependencies target again.
Note
Refresh your Eclipse project if dependencies (and therefore the Eclipse.classpath file) have changed.
If this is the first time that you have installed the Maven plugin into your Eclipse environment, you may need to add a file called settings.xml in your <user home>/.m2 directory.
The easiest way to tell if you need to do this is that there will be a warning in the console after building, stating that the settings.xml file is missing. All you need to do is create a settings.xml file with this content:
<settings/>
Rebuild, and the warning should no longer appear.
Note
You do NOT ever need to run any of the context menu Maven commands from inside Eclipse.
You do NOT need to run any Maven commands from the command line.
The Eclipse Maven2 plugin is a little bit flaky sometimes. You might need to close Eclipse to flush its memory.
If your default workspace JDK is not 1.5, you need to reconfigure the Maven external tools definitions for Rice this way:
Open Run->External Tools->External Tools Dialog... menu item.
Find the m2 build category.
Select each preconfigured Rice external tool configuration, select the JRE tab, and ensure the JRE is set to 1.5.
The default Maven2 repository location is in your user directory; however, if you have a pre-existing repository (or for some other reason don't want it in your user directory), you can alter Maven2's repository location. The current version of the Maven2 plugin has a bug that does not allow this to work (see http://jira.codehaus.org/browse/MNGECLIPSE-314), but the 0.0.11 development version available from the update site http://m2eclipse.codehaus.org/update-dev/ allows you to specify a custom local repository.
Note
If you make this change, you may have to delete and re-add the Maven Managed Dependencies library to your project build path if you have an existing, invalid, Maven-managed dependencies library.
If your default workspace JDK is not 1.5, then you also need to set the JDK compliance level to the appropriate version for the project. You can find this by right-clicking on the Project -> Properties -> Java Compiler -> Compiler compliance level. Be sure the Enable project specific settings checkbox is checked.
Be sure to turn off validation at the project level by right-clicking on the Project, then clicking Properties -> Validation -> Suspend all Validators. This can be adjusted once a successful Rice project is up and running.
If you start seeing java.sql.SQLException: Listener refused the connection with the following error: ORA-12519, TNS:no appropriate service handler found, there are a couple of things that may remedy the problem.
Increase the Oracle XE connection limit:
alter system set processes=150 scope=spfile; alter system set sessions=150 scope=spfile;
Lower the Atomikos pool size in your rice config.xml:
<param name="datasource.pool.size">10</param>
Disconnect any other clients and then restart Oracle-XE.