Coeus & Interactive Debugging

David B. HarrisonBrown University

Crash Course

“The problem with most crash

courses is that they crash.”

- Berel Wein

Presenter

David B. HarrisonSr. Programmer / AnalystBrown University

• 9 months experience with Coeus• BS and MS in Computer Science• 20 years of Software Engineering

Crash Course in Interactively Debugging Coeus

•Why?• Background• Requirements• Setting up• Real-world examples

Why would you want to do that?

• Understanding the architecture• Greater speed in solving problems• Quickly test changes, fixes, or enhancements!• Assist in making Institution-specific changes

Brown & Coeus Background

• Originally, Brown had a homemade system• Coeus @ Brown since version 4.0– Ben DiMolfetta assisted in original implementation

• Main Coeus developer/support for Brown left 11 months ago

• David Harrison joined Brown 9 months ago.• Started learning Coeus at that time.

Inspiration

• Frustrated with lack of documentation • Needed to understand the architecture• Builds were preformed on remote servers. It

took at least 15-20 minutes, just to see if a change compiled. This is a distraction.

• Using the right tools and local builds, should make the process much faster… – Goal: Stay in the “Zone”

Recent Experience

• Brown University recently completed major upgrade from Coeus 4.3.7 to 4.4.3

• Migrated 4.3.x customizations to 4.4.x– Stored procedures– Blort-loads of XML / XSL templates• The FOP Engine upgrade affected rendering of custom

reports

– Customized Email notifications

Approach

Preferred• “See One”• “Do One”• “Teach One”

Actual• Jump in• Repeat

– Drink coffee– Learn some– Do Some

“Do or do not. There is no Try.” (Jedi Master Yoda)

• Deploy• Huge sigh of relief!• “Teach One!”

Getting to know you

• What is your primary role?– Most people said “Developer” or “Support”

• Do you use revision control for Coeus?– Approximately 3 out of 12 attendees use a revision

control system.• Do you use a change management or

deployment system?– None.

Other Questions

• Planning to move to Coeus 4.4.4 or KC soon?• Formal process in place for Upgrades & QA?

Required Software

• Java• Ant• Apache Tomcat• Eclipse – Helios edition recommended

• A Database!– Oracle is recommended

• SQL / Schema explorer tool

Setting up!

•Environment •Tomcat •Eclipse

Pre-conditions

• Install the required software!• Retrieve Coeus source• Setup Tomcat• Setup & test database connection• Update the Coeus build.properties file• We’re not going to cover this part.

• Ant build– Build from the command-line, first!

Environment Variables

JAVA_OPTS = -verbose:class

Coeus Lite / Server DebuggingJPDA_ADDRESS = 11555JPDA_TRANSPORT = dt_socket

Coeus Premium debuggingJAVAWS_TRACE_NATIVE = 1JAVAWS_VM_ARGS = -Xdebug -Xnoagent

-Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=8989,server=y,suspend=n

Apache Tomcat Setup

• Define the data source• Configure Tomcat Java options• Copy libraries into Tomcat’s common lib folder

Apache Tomcat – Data Source

In the Tomcat conf directory• Add a Data Source Resource to the Context.xml file, • There are other areas where you could define the data source.

<Resource name="jdbc/coeus" type="javax.sql.DataSource“ driverClassName="oracle.jdbc.driver.OracleDriver“ maxIdle="2" maxWait="5000" validationQuery="select sysdate from dual" maxActive="4"

url="jdbc:oracle:oci:@DBServer.YourInsititution.edu:YourPort:YourOracleSID"username=“SchemaName"password=“PrettySecret"

Tomcat Java Options

• Load the Apache Tomcat “Configure Tomcat” program.

• Go to the Java tab• Add the “Java Options”

-Xdebug -Xrunjdwp:transport=dt_socket,address=11555,server=y,suspend=n-verbose:class

Tomcat Libraries

• Libraries copied into Tomcat’s common lib

Tomcat-5.5\common\lib– ojdbc14.jar (If you’re using Oracle)– log4j-1.2.16.jar– coeusmail.jar

Eclipse Setup

• Now for some fun stuff! • You do have Eclipse, right?

Setting up the Eclipse Project

• Import the Coeus project into Eclipse. We’ll use the Ant build script.

• Import the Coeus as a new Java Project• File -> New -> Project

Setting up the Eclipse Project

• New Project ->• Pick “Java Project from Existing Ant Buildfile”

Setting up the Eclipse Project

• Browse to find and select the Ant build file build.xml

Setting up the Eclipse Project

• It worked! Now there is a project called “Coeus4”

Right click & Select Properties

Select the project

Setting up the Eclipse Project

• Properties for Coeus4• Java Build Path• Libraries• Add two external jars.

(in the java JDK)– Jce.jar– Jsse.jar

• Ok!

Setting up the Eclipse Project

• Hopefully… you’ve got a Coeus4 project, with no build errors.

• What does that mean?• How can I tell if there are no errors?

Like sources of build errors

• If you get compile errors about classes not being found…

Import the source into the project…

Eclipse Debug Configurations

• We’ll setup to Debug Configurations– Coeus Lite (AKA “Server”)– Coeus Premium

Coeus Lite (Server) Debug Config

• Run -> Debug Configurations

Coeus4 Server Debug Config

• Find “Remote Java Application”

• Click on the “New” button to create a configuration

Coeus4 Server Debug Config

• Name: Coeus4-Server• Connection Props– Host: localhost– Port to 11555

Coeus4 Server Debug Config

• On the Source Tab…• Make sure that the

source is selected

Coeus Premium Debug Config

• Similar to Lite/server• Just use port 8989

Coeus.jnlp modification

• For debugging only, comment out the J2SE line, in Coeus.jnlp,

• Left in, it prevents the environment variables from being passed to the JVM. We need those!<resources> <!-- <j2se version="1.5* 1.4.2*"

href="http://java.sun.com/products/autodl/j2se" initial-heap-size="100M" max-heap-size="200M"/> -->

Starting the Environment

• Start Coeus Lite– Run Tomcat, with the Coeus WAR deployed– The Default Coeus WAR is fine

• Start the Coeus Premium– Use ‘javaws’ to point at the local JNLP file. This will

start it, and it will have the debugger enabled, listening on port 8989

– Javaws http://localhost:8080/coeus/coeus.jnlp

Starting the Environment (2)

• Eclipse– Start Eclipse– Attach debugger for Coeus Premium– Attach debugger for Coeus Lite

Debugging Techniques

• Break points and Tracing– “Andy, could you duplicate the issue you reported

on my development system?”– “Sure…” – “Aha!!!”

• Stepping through code and looking at the call-stack

• Change a variable, during run time!

Debugging Techniques (2)

• Make a change to the source code and see how it affects the functionality, immediately.

• XML and XSL• Capture XML and XSL• Fix and Tweak XSL templates outside of Coeus• Logs– Use the log to help find the right Class and line of

code to investigate– Add more logging information to Coeus

Real World Examples

• Searching for a schedule, based on ‘*’ wild-card only fails with error message.– CoeusSearch.xml

Real World Examples (2)

• “Email Link not working”– BIT00175– Link to Coeus not working in Email body in 4.4.3

What’s next?

• Coeus 4.4.4 • Coeus 4.5• Kuali Coeus

Thanks!

• Brown University– Elaine Saklad– David Boylan– Chris Moore– Jennifer Quinn– Emily Derby– Andy Krajewski

• WinMill Software– Ben DiMolfetta

(Introduction & collaboration)

• Rob Yetter• Sabarinath Nair• The whole Coeus

Consortium

Links for Required Software

• Coeus• Java JDK• Eclipse IDE for Java EE Developers• Apache Tomcat• Ant

Optional Software

• Toad Extension for Eclipse• Quest Toad• Altova XML Spy