This page holds some basic tips and recommendations for developers unfamiliar with web application development and/or other Java-related technologies that are a part of Sakai development. For extra guidance on books to turn to, see Technology Book Reviews.
If you are starting from scratch, it's recommended that you tackle the topic in small stages. There are so many different systems interacting that you should not try to understand them all at once.
Stage 1: Tomcat
Download a current version of Tomcat (5.0.28 for Sakai 1.5 : Tomcat 5.5+ is not guaranteed to work with Sakai 1.5). Unzip it in the directory of your choice and learn how to start it, stop it, and learn how web applications are laid out (they're in $TOMCAT_HOME/webapps). Change some of the pages and confirm that the changes propagate to your browser. Learn how to watch the log files in $TOMCAT_HOME/logs, especially catalina.out.
Stage 2: Maven with the Sakai source
Download and install Maven. Make sure it's in your $PATH variable. Download the Sakai source code and follow all the instructions at http://cvs.sakaiproject.org/release/1.5.0/index-dev.html . You will use Maven to build Sakai and it will deploy to your Tomcat webapps directory. You have to be comfortable with the following rhythm:
- make changes to the source code
- stop Tomcat
- deploy the changes with Maven
- start Tomcat
 | Tip It's good to watch the log even as Tomcat is starting up. You might want to alias a startup command that does something like this: $TOMCAT_HOME/bin/startup.sh; tail -f $TOMCAT_HOME/logs/catalina.out The log file catalina.out tells you what's going on while the server is starting, running, and stopping. Any error messages will show up there. Java error messages are often arcane, and it will take a while to get used to reading them. But if you really stare at them, they'll tell you something. |
Stage 3: Managing Sakai Tools
Once Sakai is running, you need to know how to use the admin MyWorkspace to add and remove sites, pages, and tools. The tools you have access to all have registration files at /usr/local/sakai/reg. Your own tool will also have to have a registration file. It is usually copied from the tool's src/reg folder to /usr/local/sakai/reg. Long before you can actually write something useful you'll have to make a basic tool show up in the admin Sites tool.
Stage 4: Copy an Existing Tool
Sakai comes with several example tools. These are in the Sakai source code directory as annc, crud, and module. (Be sure to track the status of jira bug http://bugs.sakaiproject.org/jira/browse/SAK-624 "CRUD does not work") Make a complete copy of one of these directories and use it as the basis for a new tool. At a minimum you have to change the id of the project for Maven (that's in the project's project.xml file) and the tool id and url in the project's registration file (located in src/reg). Since the registration file is going to be copied to the /usr/local/sakai/reg directory, you also have to change the filename to something unique. Now use Maven to build and deploy again, and you should be able to log in as the administrator to Sakai and add the new tool to one of your sites.
Stage 5: Make Your Changes to the Tool
You can now begin to customize the tool to your own purpose. Start with the jsp files that render the user interface. You'll find them in src/webapp. The key is to make small changes, rebuild, and make sure everything still works before you proceed. The JSP files refer to actions that are implemented in Java classes you'll find in src/java. Take small steps and use the source code in the example tools as a guide.
| Tip If you're only changing JSP files you can get away with re-deploying them without stopping Tomcat. Tomcat will recompile them on the fly. If you're changing Java files, on the other hand, you're better off stopping Tomcat before you redeploy. |
Stage 6: Everything Else
Diving into web application development in Java is a huge undertaking. You would benefit from a couple of books on the subject (see Technology Book Reviews). If you can get your head around servlets and JSPs, you're 75% of the way there, and then it would be good to turn to studying JavaServer Faces. JavaServer Faces (JSF) is a framework Sakai uses for building a web UI and wiring it to the application code on the back end.