Always Uptodate Help

Contents:

1. Creating an Always Uptodate Application

2. Configuring Always Uptodate

3. Releasing New Versions

4. Additional Notes

Creating an Always Uptodate Application


The Always Uptodate package is self contained with a minimal number of interfaces. It is designed to be as easy to integrate into an application as possible. The only things that you will need to do to add the features of Always Uptodate to your application are:

1. Keep track of the version of the application that is currently installed. You can store this in your configuration files or create a special class that stores the current version number like we do in our sample programs.

2. Provide proxy server data if your user's network requires it.

3. Add the AlwaysUptodate.jar archive to your classpath.

4. Creates an AlwaysUptodate object. You can do this automatically when the application begins or run scheduled checks or provide a menu item or button that users can use to check for an update any time they want.

Once you create a new AlwaysUptodate object, the update process has begun. Always Uptodate uses modal dialog boxes that lock your user interface to avoid any conflicts that might be caused by a user trying to interact with the application while it is being updated. Multi-threaded applications should take measures to avoid checking for an update while doing other processing. Always Uptodate supports Swing and AWT based applications. You control which version you use by passing either a Frame or a JFrame when you create a new AlwaysUptodate object.

To create an AlwaysUptodate object, use one of the 4 constructors provided:

Use this constructor for an application based on the AWT UI that needs a proxy server to download the update information.
public AlwaysUptodate( Frame parent_frame, String application_name, String version_file_URL, String current_version, String base_dir, String update_dir, String proxy_server, String port, String user_id, String password )

Use this constructor for an application based on the AWT UI that does not need a proxy server to download the update information or use the previous constructor and pass null for the proxy_server.
public AlwaysUptodate( Frame parent_frame, String application_name, String version_file_URL, String current_version, String base_dir, String update_dir )

Use this constructor for an application based on the Swing UI that needs a proxy server to download the update information.
public AlwaysUptodate( Frame parent_frame, String application_name, String version_file_URL, String current_version, String base_dir, String update_dir, String proxy_server, String port, String user_id, String password )

Use this constructor for an application based on AWT graphics that does not need a proxy server to download the update information or use the previous constructor and pass null for the proxy_server.
public AlwaysUptodate( Frame parent_frame, String application_name, String version_file_URL, String current_version, String base_dir, String update_dir )

The parameters to the AlwaysUptodate() constructors are defined as:

After the update process has completed, you can find the outcome of the update.

Always Uptodate provides 4 interfaces to tell you exactly what happened with the update process as well as the new version number of the application.

To check to see if the application was updated, use the getUpdatePerformed() method. This method will return false if there was no need to update, the update was refused by the user or an error occurred while updating. Otherwise, this method will return true.
public boolean getUpdatePerformed()

To check to see if an error occurred while updating, use the getErrorOccurred() method. Always Uptodate displays its own error dialogs, so you do not need to worry about that.
public boolean getErrorOccurred()

To check to see if there was an update available, but the user chose not to update the application, use the getUpdateRefused() method.
public boolean getUpdateRefused()

If an update occurred (getUpdatePerformed() returns true), you can get the new version number by using the getNewVersion() method.
public String getNewVersion()

It is highly recommended that you force the application to be restarted after an update since changes to classes may cause program instability since most Java virtual machines load classes on an as-needed basis. Updating a running application is completely safe except for a couple of potential problems that can easily be avoided (see Additional Notes below).

If you prefer not to embed Always Uptodate directly into your application, you can create a separate Java application to do the updating for you. It is recommended that you create some kind of mechanism to prevent a user from updating the application if it is already running.

If you prefer a hands-on approach, take a look at our AWT and Swing examples to see how easy it is to use Always Uptodate in your Java applications. We include all of the files from our website that are used to configure Always Uptodate.

Configuing Always Uptodate


The configuration of Always Uptodate on the web server consists 4 parts: the Versions File, the Release Notes files, the Affected Files files and the files to be updated.

The Versions File resides on your website and serves only to show the different versions of your application. The only real limitation of the version numbers is that they have to be of increasing value when evaluated as a Java "String" type. For example: 1.00.00 followed by 1.00.00a followed by 1.00.01 is a valid set of increasing version numbers. Note that in the Versions File, the versions are listed in order from most recent to least recent. So, you will add new versions to the top of the file causing the versions to be in decreasing order in the Versions File. This file is designed to be very small since it is the file that will be downloaded from your web site each time a check is made for a new version. If there is no new version available, the application will know in just a few seconds. The Versions File should contain nothing but version numbers. Each version number should appear on its own line. Do not include comments or anything else in the Versions File. View a sample Versions File here.

The Release Notes files allow you to tell your users what modifications have been made in each release of your software. There is one Release Notes file for each version you release. The Release Notes file must be named "version_number".relnotes (e.g. 1.00.relnotes) and must match a version number from the Versions File. There is no need to provide a Release Notes file for the very first version of the application. The Release Notes files must be located in the same directory as the Versions File. Do not place any comments or anything else in your Release Notes files that you do not want your users to see when a new update is available. Hint: We recommend that you use spaces in your release notes instead of tabs since the tabs may be displayed differently on different platforms. View a sample Release Notes file here.

The Affected Files files define which files need to be updated to upgrade the application from the previous version to the new version. These files have a strict format that must be followed in order to work properly. For each file that needs to be updated, there are three elements: the File Name, the File URL and the File Destination. The File Name is the name of the file only (no path information). The File URL is where the file can be downloaded from. This is a complete URL with full path and file name. The file name in the URL does not have to match the File Name. The File Destination is a relative path to the file's final location once installed. The path is always relative to the base_dir passed in when the AlwaysUptodate object was created. Comments can be added to the Affected Files files using a "#" in the first character of a line. There is no need to provide an Affected Files file for the very first version of the application. The Affected Files file must be named "version_number".files (e.g. 1.00.files) and must be located in the same directory as the Versions File. View a sample Affected Files file here.

The files to be updated can basically be located anywhere you want on your website (or anywhere on the net). The Affected Files file designates the URLs to download the files from. We highly recommend that you maintain complete control of the all of files needed for Always Uptodate by keeping them on your own web site where you can be sure that the files have not been modified by any other party. Always Uptodate is as safe and secure as you make your web site.

Once you have created and installed the files for Always Uptodate, you need only pass the URL of your Versions File to the AlwaysUptodate object to begin checking for updates.

Releasing New Versions of Your Application


As you release new versions of your application, you need only add the new version number to the top of the Versions File, add a new Release Notes file and Affected Files file and place the files to be updated on your web site. We recommend that you place your affected files in a version specific subdirectory to avoid confusion. It doesn't affect Always Uptodate at all, but it might help iron out a problem if you can tell exactly which files were part of each version of your application.

That's all it takes to give your applications the ability to update themselves whenever you release a new version. We recommend that you take a look at the sample AWT and Swing programs provided with Always Uptodate. Each sample has a copy of all of the files from the Renegade Software website that are used to configure Always Uptodate.

For more information about how to configure and use Always Uptodate, please visit our web site http://www.renegade-software.com/AU/.

Additional Notes


1. Maintaining Program Stability with Always Uptodate
As we mentioned above, it is completely safe to update a running Java application with Always Uptodate under almost all circumstances. There are only a few things that you need to watch out for:

Avoid creating new instances of any objects that could be updated by Always Uptodate between the time AlwaysUptodate is called and the time the application exits. Ideally, you should be able to shutdown immediately after doing an update. If you have configuration data that needs to be saved (possibly including the new version number), that is best handled by creating a configuration class that you instantiate prior to calling AlwaysUptodate and then call a method within that class to save the new configuration values. This should guarantee that the class is loaded prior to being updated so that your latest changes to the class will not affect the running application.

If you do have to create new objects between updating the application and exiting, you should not modify the construtor(s) of those classes when you update them. If you need to change the constructor(s), you should leave the old (deprecated) constructors in the class. If you remove or change a constructor that needs to be called between updating and exiting, you may receive an exception.

It is highly recommended that you do not allow the user to update the application and continue to run the application without restarting first. This is almost always going to lead to instability since some classes will have been loaded and instantiated using the old class definitions and some will load with the new class definitions. It may be tempting to perform the update check in a separate thread and allow the program to continue, but this can be very dangerous.

A Final Note on Program Stability:
Renegade Software is not responsible for any damage or loss associate with the use of this product. If you use it, you choose to do so at your own risk. We highly recommend that you thoroughly test any new release you create with Always Uptodate prior to making it publicly available. If you follow the recommendations above, you should not encounter any problems with program instability.

2. Error Recovery with Always Uptodate
Before Always Uptodate applies any application updates, it backs up (moves) all affected files to a directory called ".aubackup" in the update_dir passed in to the AlwaysUptodate() constructor. In the event of an error during the installation of updated files, all affected files are restored from the backup copies. This is sufficient to prevent any corruption of the application except in the case of a spontaneous exit of the Java Virtual Machine by either someone killing the Java process, the process crashing or a system shutdown in the middle of the update process. Always Uptodate does not currently provide any method to recover from this situation. However, the files may be manually copied or you may create a utility to copy the files to their original locations which would reset the classes to their previous state. We intend to add a recovery feature to a future release of Always Uptodate to avoid this potential problem.