Index of /~jimmc/jraceman/jraceman

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -
[TXT]LICENSE22-Dec-2009 08:12 18K
[TXT]COPYRIGHT29-Aug-2015 13:35 2.6K
[TXT]HISTORY29-Aug-2015 13:35 175K
[   ]VERSION29-Aug-2015 13:35 34
[DIR]doc/29-Aug-2015 13:38 -

JRaceman README

README

JRaceman
v1.2.3 August 29, 2015

Contents

Introduction

JRaceman is a meet/race/regatta manager written in Java and distributed under the GPL.

Home Page

Go to the JRaceman home page to download the latest version of JRaceman.

Features

(*) Except for some native code used only on Windows during installation and for registry access.

Documentation

The Tutorial Wizard, available from the Help menu, walks you through the basics of using JRaceman.

The Users Guide gives an overview of how the program is used and details about specific parts of the program.

The javadoc-generated API Reference provides detailed documentation on the packages and classes used in JRaceman (available after you have unpacked the source).

System Requirements

JRaceman was originally released in 2002, designed to run on the typical computers of that time, and while it has grown in size and power over the years, the power of computers has grown much more quickly. You should have no problem running it on any remotely recent computer.

Item Required Why
Processor 500 MHz Starting JRaceman (using a local database or a fast network connection) will take about 20 seconds on a 500MHz processor. Faster processors will of course give better results. On a typical new multi-core laptop it should start up in just a few seconds.
Memory 128 MB Graphical Java programs tend to use a lot of memory. With anything less than 128MB, your computer will run considerably slower due to swapping. 256MB or more is recommended.
Disk 20 MB, plus up to 250 MB if you need to install Java If you already have Java installed, installing JRaceman will take about 10MB, and creating the database will take about 5MB. Larger databases will require more space. Installing Java takes 100MB or more, depending on which version you install, and whether or not you install the documentation.
Java JRE 1.7 As of v1.2.3, JRaceman requires JRE version 1.7 (Java SE 7).
Operating
System
Windows, MacOS, Linux, or any other OS that supports Java 1.7 Java is now pre-installed on most platforms, or available through the standard platform package channel. For information about Java platforms and versions visit the Java home page.

Installing Java

Most platforms now either include Java or make it available for easy installation using a standard package installer. If you need to install your own version of Java, visit the Java home page to download and install version 1.7 (Java SE 7) or later.

Installing JRaceman

JRaceman is delivered in a self-extracting JAR file. You must have Java running on your system (see previous section) in order to extract and install JRaceman.

NOTE: If you are upgrading to a newer version of JRaceman, be sure to back up your database before installing the newer version, in case there are database format changes. In particular, you should create an export file from your database (this can usually be done easily by pressing the Backup button in the menu bar) which can be used to import your data into a new database if required. See the section below on Upgrading JRaceman for details.

If you download the JRaceman installer jar file on a Windows machine and it was turned into a zip file, you will need to rename it back to a jar file. If you can not see the "zip" extension on the filename in your file browser, open Control Panel, Appearances and Themes, Folder Options, select the View tab, and uncheck "Hide extensions for known file types". Then return to the file browser, where you now should be able to right-click on the file and change its extension from zip to jar.

To install JRaceman from the installation JAR file (.jar extension), double-click on the JAR file, or run the command

java -jar jraceman-N_N_N.jar
This will open a dialog allowing you to specify a destination directory, and it will create a directory called jraceman-N_N_N in the specified directory, where N_N_N is replaced by the JRaceman version number.

If you are running on Windows and double-clicking on the JRaceman jar file opens a file browser window or does nothing, you probably need to associate the jar file extension with Java. On Windows XP (from support.microsoft.com article 307859):

If you have problems running the installer, you can try running it with the debugging flag turned on, which will cause it to print more information:

java -Djraceman.install.debug -jar jraceman-N_N_N.jar

If you double-click on the installer in Windows and nothing happens, open a DOS window, cd to the folder into which you downloaded the installer, and enter the java command shown above. Any error messages should now show up in the DOS window.

Unpacking the JRaceman Source

If you want to build JRaceman yourself, or just look at the source code, you will have to unpack the source files from the src.zip archive file with the commands

cd jraceman-N_N_N
unzip src.zip
This will create a src directory with all of the Java files, as well as adding a few other files (such as a build.xml file) to your jraceman directory. You must have the ant program installed on your system in order to build JRaceman from source files. After unpacking, run "ant" to build the main jar file.

To build the war file for web use, run "ant war." This will create the file jraceman.war, which you can then copy into your web container's webapp directory.

Run "ant -p" to get a list of all of the build targets you can use.

If you want to look at the Javadoc-generated API documentation for the Java classes, you must first unpack those html files from the apidoc.zip archive file with the commands

cd jraceman-N_N_N
unzip apidoc.zip
This will create the directory doc/api with all of the API documentation in it. Alternatively, you can unpack src.zip and then run the command
ant doc
to run javadoc and create the API documents from the source files (you must have the ant program installed on your system in order to create the documentation using this command).

If you want to look at the source to the JRaceman Users Guide, or if you want to generate the PDF or HTML files yourself, you must first unpack the xml source files for the Users Guide from the xml.zip archive file with the commands

cd jraceman-N_N_N
unzip xml.zip
This will create the directory xml with all of the source files for the JRaceman Users Guide.

The JRaceman kit does not include the source to the Mckoi database. You can download the Mckoi database source from the Mckoi web site, or from the same location from which you downloaded JRaceman. You do not need the Mckoi source to compile JRaceman; the mckoidb.jar file included in the JRaceman kit is sufficient.

The JRaceman kit does not include the source to the jRegistryKey package. You can download the jRegistryKey source from the jRegistryKey web site, or from the same location from which you downloaded JRaceman. You do not need the jRegistryKey source to compile JRaceman; the jRegisgtryKey.jar file included in the JRaceman kit is sufficient.

The JRaceman kit does not include the source to the JShortcut package. You can download the JShortcut source from the JShortcut web site, or from the same location from which you downloaded JRaceman. You do not need the JShortcut source to compile JRaceman; the JShortcut.jar file included in the JRaceman kit is sufficient.

The JRaceman kit does not include the source to the JXL Excel spreadsheet reader. You can download the JXL source from the JXL web site, or from the same location from which you downloaded JRaceman. You do not need the JXL source to compile JRaceman; the jxl.jar file included in the JRaceman kit is sufficient.

The JRaceman kit does not include the source to JSF, the servlet or jsp APIs, or the commons file upload package, all of which are used in the web registration interface.

Running JRaceman

If you have not already done so, you must install Java.

JRaceman comes with a set of convenient scripts to start it in various modes (standalond, client, server). There are shell scripts with the extension sh for Unix hosts and batch files with the extension batfor Windows.

On Windows

On Windows, double-click on the shortcut set up by the installer, or CD to the main JRaceman directory and run

java -jar jraceman.jar
If you told the installer not to create a shortcut, you can manually set up a shortcut to jraceman.jar in the main JRaceman directory, with the Start-In directory of the shortcut set to the JRaceman directory.

On Unix

On Unix, run
java -jar jraceman.jar
If the java binary is not in your PATH, you can explicitly specify the path to it. For example, if you have installed JDK7 into /usr/local/jdk7, you can run jraceman with the command
/usr/local/jdk7/bin/java -jar jraceman.jar

On Solaris 2.6 or later, you can directly run jraceman.jar.

Upgrading JRaceman

When you install a newer version of JRaceman, you may need to upgrade your database. Starting with v0.3.10, JRaceman attempts to automatically determine if you need to upgrade your database, and opens a dialog offering to do so when needed. However, this may not work if your database is too old.

With an older database, you may receive a message something like this:

The state store for this database doesn't exist. This means the database version is pre version 1.0. Please see the README for the details for converting this database.
This message comes from the Mckoi database engine, and indicates that the Mckoi database format has changed. The README file referred to in that message is the Mckoi README file, which tells how to perform the Mckoi database upgrade. Rather than doing this, you should probably export from your old database and import into a newly created database.

For more information about upgrading, see the Upgrading section in the Users Guide.

Using the Web Registration Module

JRaceman includes an integrated web registration interface. This interface is implemented using JSF version 1.2 and has been tested on Tomcat version 6.0.26.

In order to use this interface, you must have a web server with a web applet container that support JSP 2.0 (required by JSF 1.2), such as Tomcat version 6. Tomcat is a well known and freely downloadable web container; if you are unfamiliar with it, please ask around to find someone with that familiarity who can help you get it set up. A discussion of JSP, Tomcat, and web apps is beyond the scope of this document.

Once you have an appropriate web container, download the war file from the same site from which you downloaded the JRaceman package.

After downloading the war file, rename it to "jraceman.war", or to some other .war name to be used on your web site. Copy the war file into your container's webapp directory.

You will need to configure your JRaceman database to support the web registration webapp, which you can do by editing values in the Database/Options and Database/ContextOptions tabs. See the Web Registration chapter in the JRaceman Users Guide. It might also be useful to search for WebRegistration in the HISTORY file for comments about recent changes related to that.

Once the above setup steps have been done, start the JRaceman database server on the same machine running the JRaceman webapp, then access the webapp from your browser using the URL that matches the name of your war file, or the name as you have configured that war file in your web server. You should see a JRaceman login page.

Bug Reports and Feedback

If you have a comment about JRaceman, or would like to report a bug, please send email to jraceman at the domain j.jimmc.org

Author and Contributors

JRaceman was written by Jim McBeath.
http://www.alumni.caltech.edu/~jimmc

The Hungarian translation was contributed by Dr. Novotny László.

The SprintTimer integration was contributed by Mark Shuter.