
   Ganymede Logo
   
                            Ganymede Upgrade Guide
                         Release 1.0.5 - 27 July 2001
                                       
     _________________________________________________________________
                                      
   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, as is the case with the Ganymede 1.0.5 upgrade, which
   introduces support for Sun's Java Web Start application launcher. 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.
   
   Now, 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. Since 1.0, I am trying to avoid
   this kind of incompatible change, 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 1.0 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 1.0 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.
   
     _________________________________________________________________
                                      
   
    Jonathan Abbey
    
   Last modified: Sat Jul 28 03:14:31 CDT 2001
