Managing applications

To serve a Java application, the packages that contain the classes and other resources that comprise the application must be stored in the DSJ serverÆs internal package database. This process occurs automatically when you install an application.

The DSJ server has JBuilderÆs Welcome application preinstalled for testing purposes.

Viewing available applications

Applications are managed from the Applications page of the DSJ server administration frame.

Each version of each application listed is represented by a separate .app file in the serverÆs AppFileDirectory directory. The list contains:

• A glyph to indicate the availablity of the application:

  Glyph	Description
  	Enabled, with no access (user name or IP address ) restrictions
  	Enabled, with restrictions
  	Disabled, with no restrictions
  	Disabled, with restrictions

• The name of the application
• A string which identifies the version, usually containing a number
• The application version date, used to determine the latest version of the application
• A short description of the application

Disabling and enabling applications

You can temporarily disable an application so that new clients cannot access it. From the Applications page of the administration frame:

1. Highlight the application to disable.
2. Click Edit App.
3. Go to the General page of the Application dialog box.

   

4. Uncheck the Enabled checkbox in the middle of the dialog box.
5. Click OK.

The .app is rewritten with the Enabled property set to false, and the application is listed as disabled in the administration frame.

To enable the application, follow the same steps and check the Enabled checkbox.

Adding applications

To add a Java application to the DSJ server, follow these steps from the Applications page of the administration frame:

1. Click New App. An empty Application dialog box appears.

   

2. Type in the information for the application. Follow the hints at the bottom of the dialog box. For example, the following information is used for the Hello sample application for JBuilder installed in the c:\jbuilder directory:

   Page	Field	Example setting
   Identification	Name* Version Version date*	Hello 1.0 use default (todayÆs) date
   Runtime	Main class* Classpath*	Hello.Hello c:\jbuilder\myclasses;jgl.zip;jbcl.zip
   * Required field

3. By default, the application is configured to be available from the localhost machine, which is sufficient for accessing the application from the same machine as the DSJ server (usually for testing), but in most cases you will want to add the actual server name so that the application is accessible from other client machines. At the same time, you can remove localhost so that client machines will not waste time checking themselves. To do this:
   1. Click the General tab.
   2. Click Available Servers in the Access group to open the Available Servers dialog box.
   3. With "localhost port 707" highlighted, click Remove Server.
   4. Click Add server to open the Add new server dialog box.
   5. Type in the hostname or IP address of the DSJ server and the default port number, 707.
   6. Click OK to dismiss the Add new server dialog box.
   7. Click OK to dismiss the Available Servers dialog box.
4. Click OK to dismiss the Application dialog box. A file name dialog box appears.
5. Type in the name of the .app file. The extension is applied automatically and the file is saved in the AppFileDirectory directory, so you only have to type the name itself. In general, this is the same name as the name of the application. Click OK.
6. Be patient. The DSJ server processes the class path and builds an .app file describing the application, using the values you typed in the Application dialog box. This process may take several seconds to complete.

The new application appears in the list of available applications. It is now ready to be distributed to the DSJ clients that request it.

For details on the .app file format, see .app file Reference.

Application versioning

When you install an application to the DSJ server, you specify a partial class path (along with other information about the application like its name, and the name of its main class). The partial class path does not include the core system class libraries like rt.jar or classes.zip, because those classes are always assumed to be available. Then the DSJ server consumes the entries on this path.

Note

The server does not attempt to determine whether any classes in the package are actually used by the application. All packages in the class path are processed.

During consumption, every package on the path is versioned--based on the date of its most recent class (or other resource)--and then stored in the internal DSJ database. Other applications using the same version of a package will all share the same package entry in the DSJ database.

You can install as many different versions of the same application as you like. The only requirement is that they each have a unique VersionNumber property.

Part of the process of establishing a long-term connection between client and server is to determine the package entries that are needed by the application; that is, which version--if thereÆs more than one--of which packages. By resolving this up front, the server does not have to search all the packages when looking for a resource; just the packages that matter. The result is that even if multiple versions of a particular package have been installed to a DSJ server, only the one that is associated with the application is examined.

On the client side, when it receives resources from the server, it stores them to a local cache file. Each application the client runs has its own cache file, based on the application name. This means that if the client tries to run different versions of the same application, they will use the same cache, which can cause problems if the cached resources are out-of-sync with the running version. Normally, this is not a problem because the client-side cache can detect whether its cached resources match those on the server; if not, the cached resources are discarded and the correct versions are downloaded from the server.

There is a cache conflict if the same machine tries to run two different versions of the same application at the same time. If the user needs to do this, they should use different cache directories for each instance of the DSJ client.

Recalculating package dependencies

Because the packages used by an application are stored in the DSJ internal database, you can actually delete the .zip, .jar, and other class files after you have added an application to the database.

Conversely, if you update class files, the DSJ server will continue to use the old packages until you tell the DSJ server the recalculate the dependencies for the application. There are two ways to do this.

If the server is already running, it is easier to do it from the Applications page of the administration frame:

1. Highlight the application to update.
2. Click Edit App.
3. Choose the General tab in the Application dialog box.
4. Click Package Dependencies.
5. Click Recalculate. This recalculates the dependencies, using the currently installed packages on the class path.
6. When itÆs done, click OK to dismiss the Package Dependencies dialog box.
7. Click OK to dismiss the Application dialog box.

If the server is not running, you can use a text editor to edit the .app file directly. Delete the Package Dependencies tag line, and all the packages listed underneath it. Then restart the server. When the server restarts, all the package dependencies will be recalculated.

Pruning the package dependencies list

When the DSJ server calculates the package dependencies list, it blindly versions and lists all the packages in the class path. This does not present a problem for clients that download classes as needed, but for clients that preload their cache, they will download all the packages in the list, even if the application never uses any classes in the package.

For those clients, you can reduce the preload cache footprint by manually pruning the Package Dependencies list, removing any unused packages. If you do not know which classes are used by the application, you can start the JRE with the -v switch to activate verbose mode. In verbose mode, classes will be listed as they are loaded.

Deploying external files

Some Java applications require external files, such as image files, data files, and DLLs for native methods. You can specify files to be downloaded to the client for each application, before the first class is downloaded to the client. These files are listed under the Extra Files tag of the applicationÆs .app file.

You can edit the list of external files from the Applications page of the administration frame:

1. Highlight the application to update.
2. Click Edit App.
3. Choose the General tab in the Application dialog box.
4. Click Extra Files.

In the Extra Files dialog box, you can add or remove individual files, or add all the files in a directory.

Locale and operating system extensions

You may create specific settings for each application for clients running in particular locales and operating systems. These settings are stored extension files: files that start with the same "application.app" root name with a locale and/or operating system name added to it.

When a client connects, it transmits its locale and operating system to the server, along with the application it wants to run. The locale is encoded as two lowercase letters for the language, and two uppercase letters for the region, separated with an underscore character (_). The server then tries to match, in the following order:

1. Language, region, and platform
2. Language and platform
3. Language and region
4. Language only
5. Platform only

which translates to searching for file names in the form:

application.app.xx_YY.operating system
application.app.xx.operating system
application.app.xx_YY
application.app.xx
application.app.operating system

where "xx" is the language and "YY" is the region. For example,

CliffHanger.app.en_US.Windows NT

is the Windows NT, US English extension file for the CliffHanger application.

If there is no match, then the base .app file is used. If the base .app file is deleted, then that application is no longer available on that server; any extension files are ignored.

Note that while the locale is strictly formatted, the platform is not, to allow for future platforms. This also means that for "application.app.anything", the "anything" is always considered to be a platform if itÆs not in the "xx_YY" or "xx" locale format. For example, if you use an editor that renames backup files to a .bak extension, then after editing the UK English extension:

CliffHanger.app.en_UK

you will end up with:

CliffHanger.app.bak

which would be considered an extension file for the "bak" operating system, if there ever is one.

To create an extension file for an application from the Applications page of the administration frame:

1. Highlight the application.
2. Click Edit App.
3. In the Application dialog box, click the General tab.
4. Click the OS/Locale Extenders button.
5. Click the Add Extender button.

   

6. Type in the Locale, Operating System, or both. When specifying both the language and region in a locale, separate them with an underscore character.
7. Click OK. This opens a secondary Application dialog box for the extender.
8. Type in the different and or additive information for the application in the Application dialog box and click OK.
9. The new extension is now listed in the list of extensions. Click OK to dismiss the extender dialog box.
10. Click OK to close the root Application dialog box.

You may also create the extension file manually by making a copy of the root .app with the appropriate name, then changing the contents of the file. Properties in an extension file override the same properties in the root file, unless they are blank. Items in a tag list are added to the root file list.

The Enabled property is ignored in an extension file. This lets you enable or disable an application and all its extensions from the root .app file.

Removing applications

To remove an application from the Applications page of the adminstration frame:

1. Highlight the application.
2. Click Remove App.

This deletes the .app file for that application, and any extension files. You can also delete these files manually.

Note

Removing an application does not delete any associated packages; the packages may be used by applications. See Managing packages for information on removing orphaned packages.