[Note for UW Calendar 2.0: This file is obsolete, but still contains some useful information. In the interests of hastening the release, I left it here unchanged from UW Calendar 1.3. Keep in mind that the information below needs updating. Write to the mailing lists if you have a problem following the instructions --- Greg Barnes, August 6, 2004] 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) 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 release comes with some very insecure settings out of the box. In particular, YOU SHOULD NOT ALLOW INSECURE LOGINS ON A PRODUCTION RELEASE (see the discussion of main.properties below). Also, the database hsqldb as shipped, with no system administrator password, probably presents another security hole or two. 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. ---------------------------------------------------- If you change the database, web server, or servlet container, or make any appreciable changes to the code, you may need to modify the application properties files. The properties files are in the properties/calendar directory. They are currently set up to work with the quickstart release. For an explanation of the properties in these files, see the file named PROPERTIES in this 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 build.properties. Once build.properties is set, just run 'ant' to compile. ------------------------------------------------------- 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 'dist' creates a distribution if you need to move yours to another machine ------------------------------------------------------- To test the servlets using a toy login, see the URL in the quickstart release's README file. To use a real login servlet (except for accessing the public events display calendar), you will need to implement some form of authentication on your web server which sets the REMOTE_USER variable for the login servlets. See the MOVING TO PRODUCTION section for a list of servlets that should be protected by an authentication scheme. The main personal calendar login servlet can be accessed via http:///uwcal/cal/index.html (assuming uwcal is the name you use for the application) There are 2 interfaces to enter and modify public events, one for less privileged users, who can only add, change and delete their own events, and one for administrators, who can modify anyone else's events, and specify who the less privileged users are, among other functions. Less privileged users can login using: http:///pubevents/pubevents/index.html Administrators can login using: http:///pubevents/pubevents/admin.html There is also the servlet uwcal.export.ExportPage. This should work much like the UWICal application (see below) with arguments <$USER startdate enddate> . This servlet also needs to be protected by an authentication scheme. --------------------------------------------------------------------- Running the UWICal application 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. ------------------------------------------------------- MOVING TO PRODUCTION To move to production, you will probably want to use a more robust database, and enable https and some form of secure authentication for security purposes. To enable https and secure authentication, it may be easier to use a different webserver, such as Apache. I'm really not an Apache expert, so I leave that as an exercise to the reader. If anyone has any pointers, please contribute them back to the project. Once you have https and authentication enabled, you will need to change main.properties and main.properties.pubevents to ensure these methods are used. The only servlets that should require authentication are uwcal.userlogin.CalLogin, uwcal.export.ExportPage, pubevents.userlogin.PubEventsLogin and pubevents.userlogin.AdminLogin. If you force authentication on other pages, guest logins will not work. ----------------------------------------------- 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 build.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). You may not need to change the db.properties file (see PROPERTIES), nor the resource reference (, near the end of html/WEB-INF/web.xml. You will, however, have to change the DataSource information. Where this is specified varies among servlet containers. In Tomcat, this is in the server.xml file (in the quickstart distribution, see quickstart/jakarta-tomcat-5.0.16/conf/server.xml, which contains this XML near the bottom: username sa password driverClassName org.hsqldb.jdbcDriver url jdbc:hsqldb:hsql://localhost:8887 maxActive 8 maxIdle 4 The easiest way to change to another database is to just modify the element above. You should change the values of the username, password, driverClassName, and url parameters, above. Alternatively, you could copy the Resource and ResourceParam elements and then change the copies, but that would require changing the in web.xml and db.properties. 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: . If you choose to use another servlet container, be aware that servlet containers define DataSources in different ways, but, as mentioned above, you should not have to change the in web.xml (as this is part of the J2EE servlet specification). You should only have to change Tomcat's and 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 the LoadCalendar class java edu.washington.cac.calendar.db.LoadCalendars Where can be resources/calendar/initialCalendars, 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 idiosyncrasy 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 (by the way, I know about the db code in the pubevents module; that's a much larger problem). 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 products I'm sure this works on now are Informix, and hsqldb. ----------------------------------------------- -------------------------- Greg Barnes January 27, 2004