Appendix A: How J-Bird is launched

Introduction

J-Bird is launched by a single program that determines what to do. For example, if J-Bird has been installed but not run, the launcher creates and populates the J-Bird database, or if the database exists, the launcher presents the main interface. Or, if the database was not closed properly by the previous run of J-Bird, the launcher repairs the database and then launches J-Bird.

The launcher was introduced in J-Bird 0.5.1, and it is a bit more complicated than the old system in which you the user determined whether you should run the database builder or J-Bird itself. There was no option for repairing the database. This appendix documents how the launcher works. It may be useful to people who wish to do the unexpected with J-Bird or to people who experience problems with the launcher.

Finding the data home

J-Bird's data and software are stored in separate directories/folders. The directory that holds data is known as the data home, and the first task for the launcher is to locate that directory. The default data home directory is in a fixed location that depends on the type of your computer. It is possible to override the default.

On Windows 98/95, "User's home" is the Java property "user.home", which seems to correspond to the MS Windows environment variable windir, which is usually the \WINDOWS directory on the system disk.

It is possible to force the data home to be an arbitrary directory by setting the Java property jbird.data.home to be the full path of a directory. To set the jbird.data.home, you'll need to edit the scripts that launch J-Bird on your system. Note that those scripts will be overwritten each time that J-Bird is upgraded and that you will have to modify the scripts after each upgrade.

If the data home directory does not exist, the launcher assumes that J-Bird is being run for the first time and creates the database if it cannot locate an old version of J-Bird that is 0.5.0 or less. If it finds an old version of J-Bird, the launcher will attempt to extract data from the old version and store them in the new data home.

Build database, Upgrade database, or run?

Each time that the launcher is invoked it must decide whether to build the database because J-Bird is newly installed, to upgrade the database because J-Bird was just upgraded or to launch J-Bird for regular use.

Repair database or not?

The launcher attempts to repair the database any time that it detects that the database was not properly closed when it was last used. It uses a property in the J-Bird.prefs file to determine whether the database was properly closed. The property is named NextRun, and the launcher attempts to repair the database if the value of NextRun is "Repair".

The value of NextRun in J-Bird.prefs is set as follows. When J-Bird opens the database it sets the value of NextRun in J-Bird.prefs to be "Repair". When J-Bird closes the database, it sets the value of NextRun to be "Run". Hence, if the database was opened but not properly closed, the launcher will see the value "Repair" and attempt to repair the database.

Command-line options (Windows and Unix only)

You can direct the launcher to dump the J-Bird database to files of comma-separated values or to restore previously dumped data without launching a graphical user interface. To do so, you'll run J-Bird as a command and pass options to the command.

To dump the database to a set of comma-separated files, run the command

	J-Bird.sh -d

on Unix or Linux. On MS Windows, run

	J-Bird.bat -d

. The files of comma-separated values will be saved in a file named CSVDump.zip in J-Bird's data directory. You can specify the archive file to which the database will be archived by naming a file after the -d option. If you specify just the file name the file will be created in J-Bird's data directory. If you specify a relative path, the path will be interpreted relative to J-Bird's data directory. For example,

	J-Bird.bat -d jbird.zip

creates an archive named jbird.zip in J-Bird's data directory.

	J-Bird.sh -d archive/jbird-060423.zip

creates an archive named jbird-060423.zip in a subdirectory of the data home that is named archive. (Note that relative paths are interpreted relative to the J-Bird's data home rather than relative to the directory that holds the software and rather than relative to the directory in which you invoked the launcher.) It is also possible to specify an absolute path.

	J-Bird.bat -d "C:\Documents and Settings\mort\stuff\jbird-060423.zip"

You can direct the launcher recreate the database from a previous dump. The database can be restored from a zip archive or from individual files of comma-separated values. To restore the database from a zip archive that is names CSVDump.zip in J-Bird's data home, run the command

	J-Bird.bat -r

if you are on a MS Windows computer or

	J-Bird.sh -r

on a Linux or Unix computer. To restore the database from a zip archive with a different name, follow the -r option with the name of the file. Relative path names are relative to J-Bird's data home. For example to restore from a file named jbird-060423.zip that is in a subdirectory of J-Bird's data home that is named archive, run

	J-Bird.sh -r archive/jbird-060423.zip

To restore the database from individual files of comma-separated values in J-Bird's data home, follow the -r option with "CSV". For example, run

	J-Bird.bat -r CSV

on an MS Windows machine.

The good old days (Windows and Unix only)

Prior to J-Bird version 0.5.1, two separate scripts (or shortcuts) were used to launch J-Bird: one that built the master species list and one that presented the primary user interface. The user ran the script to build the database, probably only once ever, and then used the primary script to launch J-Bird. The script for building the master list was called Database_Builder, and the script that launched J-Bird was called J-Bird. The script names had suffices: .sh on Linux and Unix and .bat on Windows. If the Database_Builder script resides on your computer because you have upgraded from a version prior to 0.5.2, that script will not work. Delete it.