Hello and welcome to the Education Systems - Common Services Framework wiki.

This wiki space is intended as a guide for developers and others to the Common Services Framework (CSF). This is what we call the foundation that most of our web applications are built on. CSF replaces the older "SAIS Common" framework, and is designed in a more modular fashion.

One of the main aims of the wiki is to help developers get the answers to these questions:

Where can I find stuff?

There is a lot of good stuff in CSF, but it's not always obvious what's there and where to find it. We want this wiki to help you learn what's available so you can just use it, rather than spend time writing your own version.

Where do I put stuff?

Sometimes we need to add new stuff to CSF and it may not be clear where it should go. Our wiki is here to help you put stuff in the right place.

How should I do stuff?

What are our coding standards? Should I use annotations? All these questions and more will be answered by the wiki.

And if you have a question that isn't covered here, drop us a line: csf-support@mit.edu.

If you need help setting up Eclipse, SVN, OC4J, Maven, ES Projects etc., then you're found the right place.

About this TAB

The topics presented in this TAB are primarily designed for the software developer who:

1. is a new hire and needs to configure his/her workstation, or
2. has a new workstation and needs to get it configured, or
3. has a need for a Maven WAR or JAR artifact which is not related to an on going ES project (e.g. A Proof of Concept project), or
4. has a need to add a new artifact (WAR or JAR) to an existing ES project.

Quick Links to:

• About this TAB
• Education Systems developer VMs
• Workstation configuration
  • General
  • Eclipse Indigo - Eclipse IDE for Java EE Developers
  • Eclipse MyEclipse
• Education Systems Maven projects
• Available for downloading

Education Systems developer VMs

1. Education Systems developer VMs
2. Request a ES developer VM
3. Connecting to a ES developer VM
4. Configure a ES developer VM

Workstation configuration

1. General
   • Install Java JDK
   • Install Maven
   • Install your Maven settings.xml
   • Install the Oracle OC4J 10.1.3.5 stand alone server
   • Install Tomcat 7
     
2. Eclipse Indigo - Eclipse IDE for Java EE Developers
   • Download and Installation
   • Java JDK installation and configuration
   • Subversion installation and configuration
   • OC4J server installation and configuration
   • Tomcat 7 server installation and configuration
   • Maven installation and configuration
   • m2e Subversive Connector installation and configuration
   • JVM memory configuration
     
3. Eclipse MyEclipse
   • Download and Installation

Education Systems Maven projects

An Education Systems (ES) project will typically consist of 2 Maven artifacts. These Maven artifacts are:

1. Only one Maven WAR artifact which contains all the WEB facing (i.e. jsp's, controllers, css, js, ...) components of the ES project.
2. At least one Maven JAR artifact which contains all the support (i.e. services, daos, hibernate mapping, ...) components of the ES project.

The following are the instructions on how the create and configure an ES Maven WAR or Maven JAR project.

1. Selecting names for your project
2. How to create an ES Maven JAR project using the JAR template
3. How to customize the ES Maven JAR project pom.xml
4. How to create an ES Maven WAR project using the WAR template
5. How to customize the ES Maven WAR project pom.xml

The following are instructions on how to writing unit tests

1. Using the unit test base class

Available for downloading

1. MAC plugin for managing Environmental Variables
2. project.properties (right click on this link then select Save target as....  Navigate to your ${user.dir}/<projectName> directory and click Save)
3. settings.xml (right click on this link then select Save target as....  Navigate to your ${user.home}/.m2 directory and click Save)
   This link contains instructions on how to configure the settings.xml file.
4. Other keystore downloads

About this TAB

The topics presented in this TAB are primarily designed for a project team leader who need to setup and configure an new ES software project.

Quick Links to:

• About this TAB
• Education System developer VMs
• Creating a new ES software project
• Using CSF modules
• Working with X509 Application Certificates
• Working with Hibernate Mappings
• Quick Tips
  • General Quick Tips
  • Hibernate Quick Tips
  • Maven Quick Tips
  • MyEclipse Quick Tips
  • OC4J Quick Tips
  • Tomcat Quick Tips
• DWR deprecated
• Eclipse JVM memory configuration
• Creating a new Bamboo CI project
• Project properties
• Available for downloading

Education Systems developer VMs

1. Education Systems developer VMs
2. Request a ES developer VM
3. Connecting to a ES developer VM
4. Configure a ES developer VM

Creating a new ES software project

An Education Systems (ES) project will typically consist of 2 Maven artifacts. These Maven artifacts are:

• Only one Maven WAR artifact which contains all the WEB facing (i.e. jsp's, controllers, css, js, ...) components of the ES project.
• At least one Maven JAR artifact which contains all the support (i.e. services, daos, hibernate mapping, ...) components of the ES project.

To assist the software development teams, 2 Maven project templates (for a Maven war artifact and a Maven jar artifact) have been developed.

The following are the instructions on how to use the templates to create and customize an ES Maven WAR or Maven JAR artifact.

1. Selecting names for your project
2. Using the JAR template
   • OVERVIEW
   • Creating the project jar component using the jar-template
   • Customizing the project JAR
   • Customizing the project JAR pom.xml
   • Adding a new JAR to your project
3. Using the WAR template
   • OVERVIEW
   • Section 1: Creating the project war component using the war-template
   • Section 2: Customizing the project WAR
   • Section 3: Customizing the project WAR pom.xml
4. Customizing project files
   • Customizing the project .properties file
   • Customizing the Maven settings.xml
5. Writing unit tests
   • Using the unit test base class
6. The ES masterpom
   • The ES masterpom (what it is and what it does for you) (under construction)
7. SVN patch files
   • Creating an SVN patch file using Eclipse

Using CSF modules

1. Using csf-email

Working with X509 Application Certificates

1. How to configure your web application to authenticate users with X509 Application Certificates

Working with Hibernate Mappings

1. How to configure your application to use Hibernate Mappings

Quick Tips

1. General Quick Tips
   
2. Hibernate Quick Tips
   
3. Maven Quick Tips
   
4. MyEclipse Quick Tips
   
5. OC4J Quick Tips
   
6. Tomcat Quick Tips

DWR deprecated

1. DWR has been deprecated in favor of MVC controllers.

Eclipse JVM memory configuration (do this if you are getting OutOfMemoryError: PermGen Space errors).

1. Eclipse Indigo - OC4J JVM memory configuration
2. Eclipse Indigo - Tomcat 7 JVM memory configuration
3. Eclipse myEclipse - OC4J JVM memory configuration
4. Eclipse myEclipse - Tomcat 7 JVM memory configuration

Creating a new Bamboo CI project

• The Bamboo CI project configuration (under construction)

Properties properties

• The project properties
  1. CSF Email properties
  2. CSF Local authentication/authorization properties
  3. CSF ROLES authorization properties
  4. ESAPIS and DASHBOARD properties

Available for downloading

1. MAC plugin for managing Environmental Variables
2. project.properties (right click on this link then select Save target as....  Navigate to your ${user.home} directory and click Save)
3. settings.xml (right click on this link then select Save target as....  Navigate to your ${user.home}/.m2 directory and click Save)
   This link contains instructions on how to configure the settings.xml file.
4. keystores and truststore downloads

About this TAB

The topics presented in this TAB are primarily designed for software developers who are working with either Tomcat or Oracle OC4J standalone servers on their workstation.

Quick Links to:

Tomcat 7 server

1. Tomcat 7 installation and configuration
2. Eclipse Indigo - Tomcat 7 server installation and configuration
3. Maven settings.xml configuration for Tomcat 7
4. Converting an OC4J WAR application to a Tomcat 7 WAR application
5. Converting an Tomcat 7 WAR application to a OC4J WAR application
6. Apache Tomcat 7 - The Context Container Reference at tomcat.apache.org

Oracle OC4J standalone server

1. Oracle OC4J 10.1.3.5 stand alone server installation and configuration
2. Eclipse Indigo - OC4J server installation and configuration
3. Maven settings.xml configuration for Oracle OC4J standalone server

CSF Releases and Snapshots

Overview

• The CSF Version 1.0.x series is now deprecated and will be replaced fully by version 2.0.x in the Summer of 2013.
• Version 1.0.x is now on a branch, and applications using this version will be brought to version 2.0.x by the Summer of 2013.
• Version 2.0.x is the trunk, and is using an upgraded version of Hibernate: 3.6.10. Further details are in the change logs below.

Branches

• CSF Branch r1.0.5b1 History
• CSF Branch r1.0.18b1 History

Change logs

• CSF Version 1 Change log
• CSF Version 2 Change log

Quick Links to:

Database Standards

• Concurrent Database Updates

Conventions and Standards

A special thanks to Ryan Jones for contributing to the following conventions and standards.

• Coding Standards
• Selecting names for your project
• Naming Packages, Classes, Interfaces, Methods, Variables and Constants
• Code Style

Code Reviews

• Code Review procedures and checklist.

Hibernate

Hibernate is a complete topic unto itself. Some documents explaining Hibernate esoterica and some desired practices:

• Hibernate Caching

Transactions

It is important to understand how database transactions are configured in our web apps. Here is some discussion:

Quick Links to:

CSF Architecture

• Java Web Applications
  • Architecture and Practices
• CSF design and components
  • Architecture and Practices

CSF Services

• AuthorizationServices
  • Spring Security
• Email Services
  • CSF Email Service Technical Spec
• Message Rules Engine
  • CSF Message Rules Engine Technical Spec

JUnit "Integration" Tests - Changes

July 2012: we are changing the way we code "integration" JUnit tests. See this page for details.

Acegi Security and Spring Security

We are currently in transition from the older Acegi Security framework to the more modern Spring Security.

• Authentication and Authorization in CSF framework using Spring Security
• Steve's Guide to Upgrading from Acegi to Spring Security

CSF Security and non-MITSIS Apps

In the near future (as of July 2013), we may need to be able to plug CSF Security into non-MITSIS apps - for example, administrative/SAP apps. We have done a proof of concept, showing that CSF Security can easily be used in a non-MITSIS app. Thie following page documents the details of the proof of concept and is a guide for how to use CSF Security outside the MITSIS environment.

• CSF Security in a non-MITSIS App

Hash Authentication for APIs

We have developed a "hash authentication" feature for APIs. This is an optional part of CSF Security.

• ESAPIs Hash Authentication

Switch User Once - Stateless Impersonation

Impersonation for stateless web apps (e.g. APIs). This is an optional part of CSF Security.

• Switch User Once - Stateless Impersonation

Quick Links to:

About this TAB

• This page lists all the initiatives under way in the CSF space.

Load Testing With Blazemeter

• Information on using the Blazemeter for load testing.

REST APIs

• Prototype of a web application providing Touchstone-authenticated REST APIs.More information...

ES Module Design

• We are working on a layered architecture for Education Systems Java modules (aka jar files). This document gives details...

CSF Application Upgrades

• We are upgrading CSF 1.0 and sais-common apps to CSF 2.0.  More information...

Moves

• Moves is our release management and deployment tool.  Moves docs are all collected under THIS PAGE

Hibernate Upgrade (3.2.5 to 3.6.10)

• We are working on standardizing and upgrading our use of Hibernate.  More information...
• (Obsolete) Upgrading from Hibernate 3.2.5.ga to Hibernate 3.5.6.Final More information...
• Upgrading from Hibernate 3.2.5.ga to Hibernate 3.6.10.Final More information...

Project upgrade from Spring 3.0.3 to Spring 3.1.1

• CSF has upgraded to Spring 3.1.1.  All projects using CSF must upgrade to Spring 3.1.1.  More information...

Message Rule Engine

• The Message Rule Engine, originally developed for Online Registration, has moved into CSF as a separate module. More information...

Notes

• The Notes module, intended to give users the ability to create electronic "sticky notes" is a work in progress. More information...

OS Workflow

• Open Symphony Workflow is used by several of our applications, but is no longer maintained by its authors. More information...

Test Data Builder

• We are working on providing a test-data builder framework that will provide an easy way for unit tests to acquire ready-made objects like Student and AcademicTerm. More information...

CSF Release 2

• CSF 2 was released in the summer of 2013. This will include, amongst other things, an upgrade to Hibernate 3.6. More information...

CSF Release 3

• We are planning a major release of CSF in the ??????. More information...

Using the ROLES test database for software development.

• It is now required for all software developers to stop using the ROLES production database and to start using the Role test database for software development...More information...

Using the ROLES production database for production software.

• These are the new application required properties when using the ROLES production database...More information...

Download a complete listing by server of all application properties files.

• Right click on this link then select Save target as... to download a complete listing by server of all application properties files.