To get started, you will need:

1) A Java JRE, 1.4 or higher.
2) A database (included in the quickstart release)
3) A servlet container and webserver (included in the quickstart release)

----
Note: we have noticed trouble with some earlier version of Java 1.4.  If 
you're getting NullPointerExceptions and you're using a version earlier than
1.4.2_03, upgrade to that version or later.
----

Even if you plan on using your own webserver, servlet container, and
database, it is probably best to start with the quickstart release
initially, replacing the quickstart components with your own one-by-one.

You should be able to use the quickstart release with no changes.  Follow
the instructions in the quickstart README file.  The instructions below
are if you want to start changing things.

----------------------------------------------------
SECURITY NOTICE:

The quickstart setup for tomcat and hsqldb, 
present a security hole or two (for example, the passwords for the tomcat 
users are the same and easily guessed, while hsqldb has no password at all).  
You should treat the quickstart release with caution, for example, by only 
running it on a machine that is firewalled from the outside world.

Should this not be enough warning for you, the license (../license)
contains the usual legal disclaimers of warranty.

----------------------------------------------------

Filenames and ant commands below are all relative to the calendar2 
directory.  In general, the goal of this file is to allow
you to remove all the infrastructure in the quickstart directory (except 
for the calendar2 subdirectory) and replace it with the infrastructure you
want to use in production.  So the file assumes you're operating in
the calendar2 subdirectory for the most part.

PROPERTIES FILES:

If you change the database, web server, or servlet container, or
make any appreciable changes to the code, you may need to modify various
properties files. They are currently set up to work with the quickstart
release.

Most properties are currently set in files in the following places:

local.build.properties
If you change the database or servlet container, you should change this
file so the build process continues to work.

bldfiles/defjars.properties
Defines the locations of jar files. Rather than modifying this you may want
to edit local.build.properties (see above) or add property definitions in
a file called uwcal.build.properties in your home directory.

calCore/resources
In this directory there is one file for each database you might want to use. 
Each file contains properties that apply to all applications, such as which
authorization service to use.

appsuite/clones directory.
There is one such file for each application suite to be built (currently
only the demo suite).  Each file contains properties whose values might vary 
per application.

For an explanation of the properties in these files, read the comments within
each.

There are also various files name build.properties, which are used by Ant in 
the build process, and which you should probably just leave alone.  If you 
wish to modify a property in these files, the best way to do so is to change
local.build.properties, or create a file name uwcal.build.properties in your
home directory.


----------------------------------------------------

To compile:

The easiest way to compile, deploy, etc. is to use Jakarta's Ant
tool and the Ant build file in the directory above this one (../build.xml).
Ant is available at http://jakarta.apache.org/ant/index.html,
or in the quick release.  The quick release also contains a handy pair
of scripts, ant.sh (for Unix) and ant.bat (for Windows) which help
you get around some of the more annoying Ant problems like setting
the proper classpath.

In theory, you should not have to modify build.xml.  Instead, modify
local.build.properties (for global changes) or uwcal.build.properties in
your home directory (for changes that should apply only to you).

-------------------------------------------------------
Other ant targets

'clean', 'prepare', 'compile', and 'all' do the usual things (see build.xml)

'javadoc' compiles the javadoc, such as it is.

'deploy' should move the compiled classes and other associated files to
the appropriate locations for your servlet container.  'deploy.debug' does
the same, except it creates a debug version that prints more information
to log files.

'dist' creates a distribution if you need to move yours to another machine

-------------------------------------------------------

This is a simple command-line based application to import and export
ICalendar-encoded files into the UW Calendar database.  To run it:

1) cd build/WEB-INF/classes (or wherever you compiled the target code to).
2) Get some events in ICalendar format (see docs/sample.ics).  Suppose they
are in the file $Y.ics.  Suppose $Y.ics contains at least some events
that occur between March 1 and March 31, 2002.
3) Let $USER be a user's name (it doesn't matter what, it could be anything).

  java edu.washington.cac.calendar.uwical.UWICal -s $USER < $Y.ics

You shouldn't get much output.  Try the -v and -vv options if you want some
feedback.

4)

  java edu.washington.cac.calendar.uwical.UWICal $USER 20020301 20020331

This should get you back the events in $Y.ics that occurred (at least
partially) between March 1 and March 31.

-------------------------------------------------------

To set up a new database:

You will need:

1) A database engine.
2) A JDBC driver for the database, presumably in a jar file.

Modify bldfiles/defjars.properties to reflect where the JDBC jar file is.

The application uses the J2EE standard way of accessing DataSources,
which is understood by most modern servlet containers (including Tomcat).
To use a new database, you will have to change the DataSource information.  
Where this is specified varies among servlet containers.  In Tomcat, this 
is in the server.xml file (see quickstartFiles/tomcat.conf/server.xml,
which contains this XML near the bottom):

      <!-- make the cal DataSource available in all contexts -->
       <DefaultContext>
          <Resource name="jdbc/calDB" auth="Container"
                    type="javax.sql.DataSource"/>
          <ResourceParams name="jdbc/calDB">
            <parameter>
              <name>username</name>
              <value>sa</value>
            </parameter>
            <parameter>
              <name>password</name>
              <value></value>
            </parameter>
            <parameter>
              <name>driverClassName</name>
              <value>org.hsqldb.jdbcDriver</value>
            </parameter>
            <parameter>
              <name>url</name>
              <value>jdbc:hsqldb:hsql://localhost:8887</value>
            </parameter>
            <parameter>
              <name>maxActive</name>
              <value>8</value>
            </parameter>
            <parameter>
              <name>maxIdle</name>
              <value>4</value>
            </parameter>
          </ResourceParams>
        </DefaultContext>

The easiest way to change to another database is to just modify the
<ResourceParams> element above.  You should change the values of the
username, password, driverClassName, and url parameters, above.

Once you are done, if you're using quickstart you can run 
"ant quickstart.build" to move server.xml to the proper location

driverClassName should be the fully qualified path name of the JDBC driver.
url should be a jdbc URL to access the database.  username and password
are the ones used to access the database server.

More information about DataSources and Tomcat is available at this URL:
<http://jakarta.apache.org/tomcat/tomcat-4.1-doc/jndi-resources-howto.html>.
If you choose to use another servlet container, be aware that servlet
containers define DataSources in different ways, but
you should not have to change the <resource-ref> in the various web.xml files
(as this is part of the J2EE servlet specification).  You should only have 
to change Tomcat's <Resource> and <ResourceParams> to whatever your servlet 
container uses to specify resource parameters.

You will, of course, need to create a database for the events in
your database engine.  There are some schemas in the db directory.
schema.ifx works on the database I'm using (Informix).
schema.mysql should work on a MySQL database (but I don't have
such a database, so it might have been broken the last time I changed it).
Mysql's schema is easier for humans to parse than the Informix schema, so
if you're looking to create a schema of your own, start with this one.
There is also schema.hsqldb, for the hsqldb that comes with the quickstart
release, and schema.db2, for DB2 (again, I don't have DB2 running, so
this schema might be broken).

Note that no matter what database you use, you should create default
entries per the 'insert' lines near the end of db/schema.mysql.

Once you have the db setup, you will need to import a list of public
calendars.  This can be done using your database's command tool,
and the file resources/calendar/initialCalendars.sql, or a
file that looks like it.

If you get it to work on a new database, please contribute the new
schema back to the project.

As a rule, all code to handle idiosyncrasies in a database product (e.g.,
database X won't work if you use 'select' instead of 'SELECT') should be
in the edu/washington/cac/calendar/db package.  Each idiosyncracy should
be reflected in the db.properties file.  All the field/table names should
be in Fields.java and Tables.java files in the db package.  As a result,
if you port to a new database, you should only have to change code
in the db package, and if you switch between databases, you should only need
to change the properties file.

If you find any db-dependent code outside this package, please let me
know.  If you figure out how to make the code support
DB brand X, please let me know (even if you didn't have to change a thing).
The only db product I'm sure this works on now is hsqldb.
-----------------------------------------------
--------------------------
Greg Barnes
March 25, 2005