Where are you?
--------------

The xdocs directory contains user-generated documentation. Javadocs and test
reports generated by maven are located in "target/docs".


Building the Gradebook within Sakai
-----------------------------------

The safest way is to start from the top Sakai directory (the parent of the
"gradebook" directory) and build the entire suite with "maven sakai".

Once you've done that, though, if for some reason you wish to re-build and re-
deploy just the Gradebook application, you can start in the "gradebook"
directory and run "maven sakai".


Building the Gradebook standalone
---------------------------------

As of the 2.2 release, both the Sakai Gradebook tool and a standalone
Gradebook application are produced by a normal build. Like other
"artifacts" produced by Maven, the standalone WAR will be placed in
your local repository and in the "target" subdirectory of the
standalone application subproject. (It will not, however, be copied
into your Sakai deployment!)

If you use the "standalone" flag in the Gradebook build (as shown below),
the build will also copy the file "sakai-gradebook-standalone-app.war"
to whatever directory is defined by the Maven property "standalone.deploy.dir".

1) You'll need to build Sakai in order to generate some JARs on which the
standalone Gradebook depends. Start at the top sakai directory and run "maven
sakai".

2) Edit "gradebook/app/standalone-app/project.properties" to match your build environment.
(Or you can override individual properties on the command line.) Edit a
"hibernate.properties" file to set up the database you want. By default the one
in "gradebook/app/standalone-app/src/hibernate/" is used, but you can
point to a different directory by changing the "hibernate.properties.dir"
property. Make sure that the database specified in your hibernate.properties
file has been created.

3) The Gradebook uses the Section Awareness interface to collect information on
course enrollments and user roles. Before building the Gradebook, you need to
build this integration support. Here's an example script for my local WinXP
build:

  # Start in the "sections" module, not the "gradebook" module.
  cd ../sections

  # Build Section Management, Section Awareness, and integration support.
  maven -Dmode=standalone -Dhibernate.properties.dir=C:/java/sakai/gradebook/app/standalone-app/src/hibernate cln bld

  # Go back to the Gradebook.
  cd ../gradebook/

  # Regular standalone build and deploy to my test Tomcat server.
  maven -Dstandalone=true cln bld

  # Initialize my local database with the Gradebook tables.
  maven schema-standalone

4) If you want, you can load your local database with test data. If you do
this, you can skip the "schema-standalone" step above, since the data
load will automatically create all needed tables.

  maven load-full-standalone

5) After starting your test Tomcat server, you can then go to the following URL
and browse the test data as an instructor, student, or teaching assistant:

  http://localhost:8080/sakai-gradebook-standalone-app/


Standalone database settings
----------------------------

By default, Gradebook's automatic unit testing uses an in-memory Hypersonic
database, and the standalone Gradebook application uses a file-system-based
Hypersonic database. Sakai licensing rules keep us from incorporating the
Oracle or MySQL JDBC libraries in the application's standard build, and so if
you wish to use either of those databases, you'll need to uncomment the
appropriate Maven dependency lines in the file "gradebook/app/project.xml".
(Look for "<groupId>mysql</groupId>" and "<groupId>oracle</groupId>".) The
Oracle JDBC libary isn't available through normal open source channels, and so
you'll have to add that to your local Maven repository manually.

As mentioned above, you then need to create your database and set up a
"hibernate.properties" file that can connect to it. You'll find a sample
"hibernate.properties" file for Hypersonic (hsqldb) in
"gradebook/app/standalone-app/src/hibernate/hibernate.properties".

Here's a sample for MySQL:

  hibernate.connection.driver_class=com.mysql.jdbc.Driver
  hibernate.connection.url=jdbc:mysql://localhost/sakaigb
  hibernate.connection.username=root
  hibernate.connection.password=root
  hibernate.dialect=org.hibernate.dialect.MySQLDialect
  hibernate.show_sql=false
  hibernate.hbm2ddl.auto=update
  hibernate.cache.provider_class=org.hibernate.cache.EhCacheProvider
  hibernate.query.factory_class=org.hibernate.hql.classic.ClassicQueryTranslatorFactory

  # java.sql.Connection.TRANSACTION_READ_COMMITTED
  hibernate.connection.isolation=2

And one for Oracle:

  hibernate.connection.driver_class=oracle.jdbc.driver.OracleDriver
  hibernate.connection.url=jdbc:oracle:thin:myschool.edu:1521:dbname
  hibernate.connection.username=gbname
  hibernate.connection.password=gbpwd
  hibernate.dialect=org.hibernate.dialect.Oracle9Dialect
  hibernate.show_sql=false
  hibernate.hbm2ddl.auto=update
  hibernate.cache.provider_class=org.hibernate.cache.EhCacheProvider
  hibernate.query.factory_class=org.hibernate.hql.classic.ClassicQueryTranslatorFactory