Kuali Coeus (KRCA)Developers Bootcamp

Jack Frosch – Kuali Foundation

(Lead Developer)

Bryan Hutchinson - Cornell

(Development Manager)

Topics

• About Kuali Coeus

• Tools

• Coding Standards

• Introduction/Lesson Overview

• Lessons!

About Kuali Coeus (KRCA)

• Eight partner schools– Cornell, Indiana, Michigan State, MIT, Arizona,

CSU, UC Davis, ISU

• Based on a MITs Coeus– Full Featured Research Admin suite– 13+ years of development work– Still going!– Consortium model

More About KRCA

• First Release - July 2008– Proposal Development– Budget– Grants.gov S2S

• Second Release - 2009– Awards– IRB/Human Participants– COI

• Beyond– Functional Parity with Coeus

Project/Development Tools

• Eclipse (eclipse.org)– Our primary development tool– Leading free and open source IDE– Pluggable architecture offers extensibility

• Maven (maven.apache.org)– Provides dependency management and

lifecycle goals (like Ant tasks)

• Subversion– Source Code Management and Repository

Project/Development Tools

• Confluence (www.atlassian.com)– Wiki used for collaboration

• FishEye (www.atlassian.com)– Source code visualization

• Continuum (continuum.apache.org)– A Continuous Integration server

• Sakai– Group mailing lists

Project/Development Tools

• Cobertura (cobertura.sourceforge.net)– Test coverage and reporting– Can be run by developer and part of CI

• CheckStyle (checkstyle.sourceforge.net)– Code style verification tool– Can be run by developer and part of CI

Coding Standards

• Coding standards assist readability and maintainability

• Derived from– Past experience– The Elements of Java Style (“Little Green

Book”)

Coding Standards

• Some Highlights– Favor readability over complexity– Methods should do one thing in < ~30 lines– Struts Actions and Forms should not have

business logic– JavaDoc comments required– Tests required for non-trivial public, protected

and default visibility methods

Coding Standards

– Favor using Java 5 features where applicable– Bos must override equals() and hashCode()

• Let Eclipse write them for you

– Constants must be used instead of literals, except for trivial loop indices, 0, 1, etc.

– If in doubt, check out the Little Green Book

• See Confluence Topic: KCRA Coding Standards - Post Release 1.0

How Bootcamp Works

• High-level Overview of Concepts• Discussion/Demo/Review of Code based on slides• Exercises

– Sample Application mimicking KRCA functionality

• Ask questions any time!• Be engaged - You will get out what you put in!

Lesson Overview

• Day 1– BOs / Maintenance Documents

• Exercise 1• Exercise 2

• Day 2– Transactional Documents

• Exercise 3

– Web Components - Struts, KNS custom tags• Exercise 4

Lesson Overview

• Day 3– Services

• Exercise 5

– Lists• Exercise 6

– Rules• Exercise 7

– Document Authorizer• Exercise 8

Documents and BOs

• Kuali is “Document based”

• Two Types of Documents– Transactional Documents– Maintenance Documents

Transactional Documents

• Represent a business function– Apply for funds (by creating a proposal)– Manage Human Participants (by creating a protocol,

amendment, etc…)

• Complex rules and approval process• Lots of data• Potentially long living• Focus on Transactional Documents later in the

week

Maintenance Documents

• Manage (create/alter) Reference Data

• What is “reference data”– In DB terms, it’s a table used by the entire

system as a FK from other tables– People, Organizations, Units, Sponsors, etc…– What else would be reference data?

• Simple documents to perform CRUD operations

Business Objects

• Business Objects (BOs) are Java Beans– Properties– Getters/Setters

• Two categories– Reference Data (CRUD via Maint Docs)– Those used in Transactional Documents

(Document Composition)

• Map to a single table in the DB

Spring BeanData Dictionary (DD)

• Controls the behavior of BOs

• Defined in Spring Bean XML– Named like <moduleBeans>.xml

• E.g. AwardBeans.xml, BudgetBeans.xml

– Inquiries and Lookups– Attributes - Properties of the BO

• UI Controls - Lookups, Maint Docs, Trans Docs• Size & Shape Validation• Required-ness

Database - OJB

• Kuali uses OJB as an ORM tool– OJB - ObJectRelationalBridge– ORM - Object-Relational Mapping

• Configure

• Write Java Code (not SQL)

• Related data elements are stored together

• Model complex database relationships

Using OJB

• OJB Repository XML• Class Descriptor

– Define the Java Class and the Table Name

• Field Descriptor– Java Property Name– Column Name– JDBC Type– Conversion (boolean to char, custom datatypes, etc…)– Primary Key– Optimistic Locking

OJB - Getting more advanced

• Model Relationships– Collection Descriptor– Reference Descriptor

• More on these later ...

Demo / Code Review

Exercise 1

OJB - repository.xml

• Reference Descriptor– Relationships to Reference data– 1:1 (Proposal:Sponsor)– Not saved/deleted when the related object is saved

• Collection Descriptor– Relationships where a parent can have many children– 1:M (Proposal:Investigators; Investigator:Unit)– “Reverse Foreign Key”– Save with the Parent

Maintenance Docs

• How we manage Reference Bos• XML based:

<BO Class Name>MaintenanceDocument.xml

– BO Class– Maintainable Class - API for customization– Business Rules - API to perform validation– Document Authorizer - Customize AuthZ for a doc– Document Type - Reference to KEW– Maintainable Section(s) and Item(s) - what and how

attributes are presented – Attributes, Locking Key, Default Existence Checks…

Values Finders

• User to present a list of options in the UI– Drop-down– Radio Group

• Queries the database and returns a list of valid values• PersistableBusinessObjectValuesFinder

– 80% - BO Class, Key/Label Attributes Names

• Custom Values Finders – 20% - Extend KeyValuesBase, Implement KeyValuesFinder

• XML (DD) and Code (Class file)

Demo / Code Review

Exercise 2

Database - JPA

• Kuali is migrating to JPA/Hibernate for ORM– JPA: Java Persistence API– ORM: Object-Relational Mapping– Hibernate is the JPA Provider

• Configured in META-INF/persistence.xml and META-INF/orm.xml

• Object properties and relationships are modeled in BOs using JPA annotations

Using JPA

• Persistence.xml defines Persistence Units– Define a datasource; i.e. Oracle, MySQL– Provider properties; i.e. for Hibernate

• Orm.xml is used to– Declare global sequences– Declare entity mappings (i.e. when not using annotations– Declare lifecycle callback methods

… and more

Using JPA

• JPA annotations on BOs@Entity: Indicates object is persistable@Table: To name the table@Id: Field(s) forming primary key@Version: Field for optimistic locking@Column: To name the column, specify length

(String data), precision and scale (numeric data), and other column data

Using JPA

• Id values are auto-generated by JPA• Version field is used during updates to determine if

record has been update (Optimistic Locking)• KRCA uses Pessimistic Locking of its BO

documents, so Optimistic Locking exceptions are rare events

JPA - Getting More Advanced

• Object relationship annotations are used to model relationships between Bos@Embeddable: An entity without a table@Embedded: Included embedded entity columns

in same table@OneToOne: One-to-one with join@OneToMany: Most frequent relationship@ManyToMany: Uses intermediate join table

Transactional Documents

• Composed of a Document class and multiple BOs– Document Composition BOs have a reference to

the Document class/table (FK Relationship)

• Transactional Document classes are special BOs– Super BOs with additional behavior

Transactional Document

• Similar to Maint Doc DD files– Add Attributes (since these are BOs)– No lookups (we use KEW for Doc Search)– No Inquiries

• Similar to other OJB mappings– Lots of relationships defined– Other mappings should not refer back to the

Document class

Demo / Code Review

Exercise 3

Web stuff in Kuali/KRCA

• Struts– Pseudo MVC– Forms, Actions, Mappings

• Struts in Kuali– Heavily customized– Addresses common Struts anti-patterns– Simplifies development

• Single Action Mapping

Struts Action Classes

Object Hierarchy for KRCA:

-KraTransactionalDocument

----KualiTransactionalDocumentBase

------KualiDocumentActionBase

--------KualiAction

----------DispatchAction

Struts Form Classes

• Document is placed in the Form• POJO Form Base handles type conversion • Object Hierarchy for KRCA:

-ProposalDevelopmentForm----KualiTransactionalDocumentFormBase------KualiDocumentFormBase--------KualiForm----------PojoFormBase------------ActionForm (Struts base form)

Building the UI

• JSPs/Custom Tags• JSTL and JSP Expression Language

– Preferable to Struts tags when possible

• Kuali Rice Tags– page.tag and documentPage.tag– tab.tag– documentControls.tag– htmlControlAttribute.tag

KRCA Custom Tags

• Build complex JSPs

• Maintainability

• Methodology is approximate, but in general:– 1 JSP per page– Generally, 1 .tag per panel on the page

HTMLControlAttribute.tag

• <kul:htmlControlAttribute />

• Replaces struts <html:xxx />

• Uses Spring Bean entries to determine:– Type of control (text, drop-down, etc)– Length– Max Length

• Spring Bean Attributes

Demo / Code Review

Exercise 4

Services and DAOs• Services: Implements Business Logic not in BOs

– Perform a calculation; Save a Document

• Services are defined as Interfaces and Implemented as classes

• Spring manages the resolution of Interface to actual code - Spring Beans XML

• Accessing Services– Dependency Injection– Service Locator (KraServiceLocator)

• Data Access Objects - DAOs– Similar to Services, but have knowledge of the data model

Demo / Code Review

Exercise 5

Lists of Data

• Old stuff– JPA, BOs, Spring Beans, etc

• New stuff– Document changes

• Special getter• Deletion Aware Lists

– Action Form - Methods for add/delete– JSP/tag - Accessing properties of a list

Demo / Code Review

Exercise 6

Rules and Events

• Events - A way to evaluate a rule when an action occurs– Automatically invoked via frameworks (Save,

Route, etc…)– Custom events (add or delete a BO from a list)

Rules

• Beyond size & shape validation from the DD

• DocumentRuleBase - Customize save/route/etc… rules

• Custom Rules - Implemented in Rules classes; Validate pretty much anything about the document; Return true/false

Demo / Code Review

Exercise 7

Error Messages

• Give context to errors– Display error messages on the appropriate panel– Highlight fields that have errors

• Generated from DD

• Generated from Rules classes

Audit Errors

• Similar to Error Messages

• Allows users to continue working on their document and defer validation until ready

• Errors and Warnings

• Provides a link to where the error is occurring

Document Authorizer

• Determine the level of access that a user has to the document– Read Only– Full Access– Somewhere in between

• Document Actions– What actions can a user take on a document– Implemented in JSPs via <kul:documentControls />

• Who can initiate a document

Demo / Code Review

Exercise 8