Note: If you are reading this as the UPGRADE
text file
in the Ganymede distribution directory, you are missing a bunch of
hyper-links that link to extra information about many topics
discussed. If you can, view this document with a web browser as
doc/upgrade.html
.
Upgrading Ganymede |
Upgrading Ganymede generally amounts to upgrading the jar files that contain the Java class files that make up the Ganymede server and clients. When a new release of Ganymede comes out, you'll generally want to upgrade your server and your clients together, as it is sometimes necessary to make incompatible changes to the network API's that the clients use to talk to the server between versions of the Ganymede distribution.
Upgrading the clients is extremely easy, as there is almost never anything to be done other than to replace the client jar files. Sometimes the support files that are used to launch the clients may change. At the worst, you can simply delete the old clients and re-install. More on this later.
The hardest thing to upgrade is the schema kit that takes care of backend network updates when transactions are committed in the Ganymede server. Generally, the backend scripts that take files emitted by the Ganymede server and propagate them into your network are heavily customized for local use, and you will not want to lose that work. We'll go into greater detail on this as well.
Upgrading the Ganymede Server |
The first thing to do when upgrading the Ganymede server is to make a backup copy of your existing server installation. Shut down your existing server, create a tar file of your existing server directory, and put it in a safe place. You may also want to use the xml client to dump a copy of your current database to an XML file for safekeeping, just in case.
Note that it's very important to shut down your existing server cleanly before performing an upgrade. The database file format may change slightly between versions of the Ganymede server, and Ganymede's data loading routines currently take more care at handling version differences when reading the ganymede.db file than when reading the transaction journal. Cleanly shutting down the server gives the server an opportunity to coalesce all transactions into the ganymede.db file, and will help avoid problems in the upgrade.
Now, assuming you've done a clean shutdown of your old server and made backup copies of everything, you'll want to take the new Ganymede distribution and unpack it, configure it, and run installServer to install the new server code into a scratch directory.
Once you have installed the new server into a scratch
directory, you can go ahead and copy the new ganymede.jar and ganymedeServer.jar
from the scratch directory's jars
directory into your
existing server's jars
directory.
That is generally all that you will have to do to upgrade your server. The Ganymede server is designed to retain upward compatiblity with all of its data files, including especially the ganymede.db file. Newer servers can load and use ganymede.db files from any version of Ganymede released in the last couple of years, but if you are upgrading from a very old release (before 0.99), you may have problems. If worst comes to worst, we've got that backup copy of everything.
The more typical problem you'll encounter is a compatibility problem between the schema kit you have installed and the new ganymedeServer.jar file. The custom code in a custom.jar file is meant to be compiled against the contents of a specific ganymedeServer.jar file, and it is good practice to recompile your custom code, just to be sure.
Assuming that you are using a schema kit that is structured in
the same way as the Ganymede 1.0 userKit, the way to do this is to
cd to <server>/schema/src
and run the
build
and buildJar
scripts. If the
build and buildJar scripts compile and install your code without
problems, you are probably done with the server upgrade.
If not, take your backup copy and restore the original state of
the <server>
directory from your backup.
Keep in mind during all of this that all of the server scripts are custom configured to run in the location in which they are installed. If you try running your backup copy in a different location than it was originally installed, you'll find things not working properly. The jar files don't care, obviously, but don't think that the server you installed in the scratch directory can be moved to where your old server was running. If you want to completely reinstall from scratch, install the server where you want it from the beginning.
Upgrading the Schema Kit |
It is possible, however, that your schema kit rebuild won't work properly. This generally means that something in the server has changed in an incompatible fashion. (This is, in fact, guaranteed to have happened if you try and upgrade a schema kit designed for Ganymede 1.0 for use with a Ganymede 2.0 server. See the 2.0 Upgrade document for details, there.) Generally I try hard to avoid incompatible changes of this kind within a major version series, but if it happens, it should be noted in the Ganymede distribution's CHANGES file.
Alternately, it may be that your rebuild worked fine, but you have seen that a new version of the schema kit that you are using has been released, and you want to upgrade your schema kit, possibly even without upgrading the server proper. This is a more tricky issue, as you will have customized a lot of the files in your server's schema directory in order to interconnect the files generated by Ganymede with your network.
This discussion will be assuming that you are using a schema kit patterned after the Ganymede userKit. If you are using one of the pre-1.0 "schema kits", like we use at ARL:UT, or if you have designed your own custom code distribution without using the userKit as a template, you'll have to figure out how to do this process by analogy.
Any schema kit upgrade you download should include a CHANGES file that will warn you of any things you'll need to look out for in doing the schema kit upgrade, as well as a description of what benefits you can expect to see from performing the upgrade.
Before attempting to perform any schema kit upgrade, you will
want to have shut down and backed up your entire server directory,
as discussed above. Once this is done, you should rename the
<server>/schema
directory to something like
<server>/schema.save
.
Once the schema directory has been renamed, you can run the
installKit
script from the newly downloaded schemaKit
distribution. installKit
will ask you for the name
of the directory where your server is installed. Tell it the
location of your existing server directory, and
installKit
will compile all of the custom code in the
new schema kit against your server's ganymedeServer.jar
file, and integrate the new schema kit into your existing server
directory, creating a new schema
directory
underneath your <server>
directory, alongside
your pre-existing schema.save
directory.
If the installKit
script fails for some reason,
you haven't lost anything. You can just delete the
schema
directory it was trying to create and rename
your schema.save
directory back to
schema
to put the old schema kit back in place.
Assuming it succeeds, though, you need to do the next step,
which is to migrate your backend scripts forward. In the simplest
case, where you don't care about any improvements in whatever
backend scripts are provided by the new schema kit, and the new
schema kit's logic for interfacing with its build scripts has not
changed, you can generally just replace the new schema kit's
output
directory with the output
directory for your schema.save
directory. The
Ganymede 1.0 userKit is designed so that all files and scripts
involved with the backend update process are stored in the
<server>/schema/output
directory, so if you
move your old output
directory forward, you should
keep everything on the backend working just as before.
If the new schema kit includes new features in the backend,
you'll probably want to either copy some of the scripts from the
new kit's output
directory, or at the very least look
at the files and see if you need or want to make any manual edits
to incorporate new features. Again, read the CHANGES file in the
new schema kit for details.
Once you have completed this process, you can start your server
up again, and all should be well. If not, you've got that backup
copy, and you can just recreate your <server>
directory as it was before your attempted upgrade.
Upgrading the Ganymede Clients |
Upgrading the clients is a lot easier than upgrading the server, but you will often need to do both at the same time. Upgrading the clients without upgrading the server may cause a failure of the clients, as they attempt to speak to the server using a newer version of the network API's than the server can handle. If you upgrade the clients, you should plan on upgrading the server, and vice versa, generally.
Again, before you do anything to your existing clients, you should make a backup copy of everything. Upgrading the clients is easy, but if you find that your server upgrade fails, you will need to revert the clients as well as the server.
The easiest way to upgrade the clients is to simply delete the old clients (scripts and jars and all) and re-run the installClient and installWeb scripts from the new Ganymede distribution that you have downloaded.
If you have made significant local customizations to the client scripts or web forms, you can do a more nuanced upgrade by just taking the new jar files and incorporating them into your existing client directories.
In this case, all you need to do is to run installClient or installWeb to get the new jar files installed into a scratch directory. Copy ganymede.jar and ganymedeAdmin.jar from the scratch directory to your old client directories, and you're set.