Netbeans Development

Prerequisites

You will need the following items to complete these instructions:

Each of the following should be installed on your local system prior to installation of Netbeans.

(Assumes Mac OS X 10.9 "Mavericks" or higher)

• Java 1.7 or greater
• SVN Client 1.7.10 or higher  go to http://www.wandisco.com/subversion/download#osx and click on "Mac OSX 10.9 - Mavericks - Subversion - Client Only" to download install package
• Tomcat 6 or higher (bundled with Netbeans)
• Apache ANT (version 1.9.4 or higher)
• Apache Maven (go to http://maven.apache.org/ to download Maven)
• SSH or Kerberos ticket access to UConn Subversion environment
• Mavericks may not include a .bash_profile file for your user environment $HOME. Or, if you need to simply add applications to your $PATH you can create a new file for the app under /etc/paths.d and add in the relevant locations
• Mavericks does not come with the Apple XCode developer tools installed. You will most likely need to download these from the App Store and agree to the terms of service upon installation.

Download Netbeans

• Go to https://netbeans.org/ and under the DOWNLOAD tab you should download the 7.4 "JAVA EE" package of Netbeans.
• On the DOWNLOAD page, select the option for 7.4 from the menu at the top of the page
• UCONN is currently running version 7.4 (or 7.3) which is compatible with all environmental frameworks.

Install Netbeans

• Follow the installation instructions from the Netbeans download package and install the .DMG file (per the installer)
• Startup Netbeans and choose "Preferences"
• In the Options screen, select Miscellaneous and then the Versioning tab, select "Subversion" under Versioning Systems and then "CLI" under Preferred Client
• Under Path to the SVN executable file choose the location of your local SVN client. In MAC OS X you can find this by opening a terminal window and typing which svn (instructions below)
  
  

Configuring SVN Connection

which svn

Checking Out a Project in Netbeans

• Next, you'll need to "check out" a code project from Subversion using Netbeans. To do this, go to the Team menu, and choose Checkout
• Use repository path https://svn0.uits.uconn.edu/kuali for UConn's Kuali-related projects (KFS and RICE)
• Enter the path and click Next (ensure you have authenticated with your Kerberos credentials before you do this!)
  
  

• On the next screen, choose Browse and select the folder you'd like to check out (trunk, branches, etc)
• After selection is complete, check the Skip <selected-folder> and checkout only its contents box, and then select the path where you'd like your code to reside locally under the Local Folder path
• Choose Finish and your code should begin to download from the UConn Subversion repository.
  
  

(Example of SVN project browsing window)

Configuration

Configuring a Tomcat Instance

Select the "Services" tab and right click on "Servers". Select "Add Server" and choose Apache Tomcat. Click "Next".

Browse to server location and select the path where your local Tomcat installation is located (EX: /usr/local/apache-tomcat-7.0.55)

Enter the USER and PASSWORD of an account with "admin" or "manager" rights to your local instance

Under "Servers" right-click the Apache Tomcat instance and choose "Properties". 

Select the "Platform" tab and enter the following values under "VM Options" then select "Close"

-Xmx512m -XX:MaxPermSize=256m

Finally, right-click your Apache Tomcat instance and choose "Start". You should see a notification of successful startup in the log area along with a "Web Applications" sub-folder under your instance in the "Services" area.

Tomcat Instance configuration is now complete and ready to act as the servlet container for your Netbeans projects!

Installing the Oracle JDBC drivers

You will need to install Oracle's JDBC drivers into your local .m2 (Maven) repository to avoid failing builds on your system. To do this, perform the following steps.

1. Download the Oracle driver JAR files from the below links here or via their OTN site (requires account)
   ojdbc6.jar
   ojdbc14.jar
   
   

2. Once you have downloaded the JAR files, in terminal navigate to their location, and install them into your local Maven repository using the following commands.

   mvn install:install-file -DgroupId=com.oracle -DartifactId=ojdbc14 -Dversion=10.2.0.3.0 -Dpackaging=jar -Dfile=ojdbc14.jar -DgeneratePom=true

   mvn install:install-file -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion=11.2.0.2 -Dpackaging=jar -Dfile=ojdbc6.jar -DgeneratePom=true

3. You should see "Build Success" after running these commands, and will have installed the drivers properly to be used with your local Maven project builds.
4. You may also need to copy the Oracle drivers into your local Tomcat directory. If you are able to successfully build KFS following the later steps in this guide, but Tomcat FAILS to start the application throwing SQL errors similar to "Listener unable to start: unable to load driver" you should then copy the ojdbc6.jar file into the <Catalina_Home>/lib on your local system. Stop and restart Tomcat and hopefully this will resolve the issue.

KFS Project Configuration

1. Edit your kfs-build.properties file in your home directory (default $HOME is /Users/<username> on MAC OS X)

   Set the institution.project.directory to path of your project

   # Use these properties to include institution-specific build and source files
   institution.project.directory=/Users/<username>/<project_name>

2. Edit the build/project/web.xml file
   
   Remove the following lines/values from the XML file and save it.

      ${monitoring.filter}
      ${monitoring.mapping}
      ${monitoring.listener}

   
   
   

3. Edit dev-build.properties

   Add the following lines to the top of the file replacing the value <user_id> with your supplied UCONN netid.

   deploy.local.cas.server=false
   
   login.user=<user id>
   
   authentication.filter.definition=<filter>\
   \n\t\t<filter-name>DummyLoginFilter</filter-name>\
   \n\t\t<filter-class>org.kuali.rice.kns.web.filter.DummyLoginFilter</filter-class>\
   \n\t\t\t<init-param>\
   \n\t\t\t\t<param-name>loginUser</param-name>\
   \n\t\t\t\t<param-value>${login.user}</param-value>\
   \n\t\t\t</init-param>\
   \n\t</filter>
   
   authentication.filter.mappings=<filter-mapping>\
   \n\t\t<filter-name>DummyLoginFilter</filter-name>\
   \n\t\t\t<servlet-name>action</servlet-name>\
   \n\t\t</filter-mapping>\
   \n\t\t<filter-mapping>\
   \n\t\t\t<filter-name>DummyLoginFilter</filter-name>\
   \n\t\t\t<servlet-name>dwr-invoker</servlet-name>\
   \n\t\t</filter-mapping>\
   \n\t\t<filter-mapping>\
   \n\t\t\t<filter-name>DummyLoginFilter</filter-name>\
   \n\t\t\t<servlet-name>batchFileUpload</servlet-name>\
   \n\t\t</filter-mapping>

   
   
   

4. Edit the build.xml file

   In the dist-local section add the following lines after the </if> tag

   <echo message="Compiling Source from ${source.directory} into ${classes.directory}" />
           <javac destdir="${classes.directory}" srcdir="${source.directory}" includeantruntime="false" source="1.5" target="1.5"
                  debug="true" fork="true" memoryinitialsize="${compile.min.memory}" memorymaximumsize="${compile.max.memory}">
               <classpath refid="compile.source.classpath" />
           </javac>
           <copy todir="${classes.directory}">
               <fileset dir="${source.directory}" includes="${non.java.resources}" />
           </copy>

   
   This will insure that the classes are compiled and inserted into  the <project path>/work/web-root/WEB-INF/classes directory

   
   
   

5. Installing the RICE jars

   You can either build the latest Kuali RICE jar files by compiling a local RICE project, or by downloading them from the Subversion repository. They are located in the branch named RICE-JARS under the KFS project.
   Once downloaded to your local system, copy the JAR files into /build/kfs-lib in your KFS project.

   

6. Building KFS Locally

   
   Instead of using the  hammer "BUILD" icons to build the project, you will want to explicitly run the targets under build.xml in the project menu
   First, under build.xml highlight the task "clean" and right-click it. Choose "Run Target". You should quickly see, "Build Successful".
   
   Second, right-click "dist-local" and choose "Run Target". This will take longer and should say "Build Successful". At this point you have successfully built the KFS application and it is ready to be started in Tomcat!

   

    

   Finally, ensure you are currently tunneled into a non-prod uconn database, then in the "Services" tab, right-click your Tomcat instance, and choose "Start". You will see Tomcat start successfully. 

   
   You should then be able to access your local KFS build in your browser by going to http://localhost:8080/kfs-dev

Configuring KFS Project to a Test Database Instance

You will most likely want to connect your local KFS project to a non-production database instance within the UCONN Kuali Infrastructure. Follow these steps to do so.

1. Coordinate having your SSH "shared key" from your system setup to the UCONN Gateway server. This will allow you to securely tunnel to the database instance. The SSG group can assist with this step.

2. Once configured, open the TERMINAL program on your Mac and ssh to the gateway server. The first time you do this, you will be prompted about the connection with a message similar to below.

   The authenticity of host 'gateway.uits.uconn.edu (137.99.23.11)' can't be
   established.RSA key fingerprint is
   bf:bb:dc:40:93:90:7a:fa:69:24:4b:77:e0:ad:61:fc.
   
   
   Are you sure you want to continue connecting (yes/no)?
   

   Answer "yes"

3. Ensure you have configured you local kfs-build.properties file with the DB connection information similar to below

   # Datasource configuration properties
   # these properties are related to ${build.environment} - you should review them, if you change that property
   # you will need to obtain the values for these properties for a given ${build.environment} from someone on the project
   mysql.datasource.url=jdbc:mysql://localhost:3306/<sid>
   oracle.datasource.url=jdbc:oracle:thin:@localhost:1521:<sid>
   
   # KFS DEV
   datasource.username=<db_user>
   datasource.password=<db_password>
   
   # Rice datasource and url
   rice.server.datasource.url=jdbc:oracle:thin:@localhost:1521:<sid>
   
   # RICE DEV
   rice.url=http://kualidev.uconn.edu/kr
   rice.server.datasource.username=<db_user>
   rice.server.datasource.password=<db_password>

4. If you experience an error in JAVA with Oracle stating "security: illegal key size" you will need to download the latest Oracle JCE Unlimited Strength Jurisdiction files. They are available here for JAVA.
   Once you have accepted the license agreement and downloaded the .ZIP file, place the local_policy.jar and the US_export_policy.jar files into the following path on your system. 

   /Library/Java/JavaVirtualMachines/jdk1.<version>.jdk/Contents/Home/jre/lib/security

Rice Project Configuration

There is no configuration necessary for a local Kuali RICE project.  However, it best to build rice from the command line using the following Maven commands:

mvn clean
mvn -Dmaven.test.skip=true compile install

Debugging

Remote

The first thing is you must have the source code on your local machine and open in NetBeans. 

Then click on the "Debug" menu item then "Attach Debugger"... the following will display

Set "Host" to the server you are targeting (contact the Configuration Manager to have debug enabled before you attach the debugger).

Set "Port" to 8000.

Login and run the application on the server.

KFS Local Project

Debugging KFS requires a little different setup.  After building KFS go to the "Servers" tab and start Tomcat in Debug Mode.

Then click on the "Debug" menu item then "Attach Debugger"

Set "Host" to localhost.

Set "Port" to 11550.