Blitz Installation Guide

Table of Contents

  1. Installation Choices
  2. Getting Started
  3. Running Blitz
  4. Memory Usage
  5. Administration
  6. Appendix A - Storage Models
  7. Appendix B - Configuration Variables

Installation Choices

Installer

GUI Install

If you're a new user or just want to get something up and running, it's recommended that you download the installer which includes a simple readme and does most of the configuration work for you. The installer package is named installer_pj_n_nn.jar where n_nn is the release version number. Note that you'll still need to download and install the appropriate version of JINI - see required packages.  To run the installer use java -jar which will display a simple GUI for gathering paths and port settings.

Headless Install

The installer can also be run in headless mode (command-line install) where one should specify the paths and port settings as follows:

java -jar installer.jar JDK_Home Jini_Home Install_Dir HTTP_Port

or

java -jar installer.jar Jini_Home Install_Dir HTTP_Port 

Manual Install

If you're an experienced user who needs ultimate control over installation layout or a developer seeking to make modifications to Blitz, you will wish to download either a binary or source distribution and read the rest of this guide which will guide you through the installation process.

Getting Started

First, ensure that you have installed the required packages.

Second, if you are going to run blitz on JDK 1.4 you will need to modify the configuration files (located in the config directory), substituting backport-util-concurrent50.jar with backport-util-concurrent.jar.

Blitz is fully integrated with JINI 2.1 so the preferred method of startup is via the ServiceStarter. However, it's possible to run Blitz, for test purposes, in a standalone mode.

If you've downloaded the source distribution, please read the Developer's Guide and ensure you've compiled the Blitz .jar's (once you've done the necessary editing of build.xml you can create the .jar's with a simple ant all.

Assumptions

For the purposes of the following examples, I assume that:

Configuration Basics

Blitz is configured via a configuration file such as the example blitz.config file. This file contains options for determining security configuration, remote functions and core functions such as the storage model (see above).

Blitz implements a concept of Storage Models which allows the user to customize the level of persistence provided. The default setting is transient but, should you wish to change this, please read Appendix A.

Additional configuration files are required for use with the ServiceStarter:

Regardless of the storage model chosen, Blitz may need to, at least temporarily, persist it's state so ensure that you have properly configured the appropriate entries in the core config file (these are the configuration parameters persistDir and logDir in the configuration file). This is also important should you wish to "clean up" after a Blitz instance as you must delete the contents of the persistence and log directories specified by the configuration parameters.

Note: You must configure the persistence and log directories as described above. Other default settings can be left alone though you should probably review the initialGroups setting (particularly if you choose to not use Brian Murphy's scripts). You should also look at increasing the cache sizes to suit your hardware.


Running Blitz

Starting JINI

Before starting Blitz, you should start up the necessary JINI services. We can do this using Brian Murphy's starter kit scripts as follows:
cd /home/dan/jini/jini2_1/jini-start/example/scripts

./urun httpd

./urun jeri-transient-reggie

./urun jeri-transient-mahalo

You may also find it useful to run the ServiceBrowser so you can check that things are performing as expected:
./urun jeri-browser
Now we must start a codebase server for Blitz:
./urun httpd -port 8081 -dir /home/dan/src/jini/space/lib
If you plan to deploy an Activatable Blitz instance you will also need to start either Phoenix or RMID. Assuming you choose to use RMID (note that there are various security options that RMID doesn't support):
rmid -J-Djava.security.policy=/home/dan/src/jini/space/config/policy.all

Using ServiceStarter

First, edit the configuration files as desired (you will almost certainly need to alter the blitzCodebase, jiniRoot, dbLib, blitzRoot variables and possibly dbVersion). To start an Activatable Blitz instance:

cd /home/dan/src/jini/space/

java -Djava.security.policy=config/policy.all -jar /home/dan/jini/jini2_1/lib/start.jar config/start-act-blitz21.config
Note that the default configuration files expect to create a log for the shared activation group in /tmp/sharedvm.log which you will need to delete if you wish to start again from scratch, re-registering the Blitz instance etc. To start a non-activatable instance:
cd /home/dan/src/jini/space/

java -Djava.security.policy=config/policy.all -jar /home/dan/jini/jini2_1/lib/start.jar config/start-trans-blitz21.config

A Word on Configuration Files

Example configurations for JINI 2.1 can be found in the config directory and have a 21 subscript. Those configurations without the subscript are examples of scripts which provide backward compatibility with JINI 2.0. Note that existing Blitz scripts from releases prior to Blitz Pure Java 1.13 will need modifications in line with these examples.

Memory Usage

For background you should read these:

Blitz uses it's cache to hold both live and dead (taken or lease expired) Entry's. It only clears it's cache once it is full.

i.e. If you set the cache size to 100 and you have only five entry's with one writer and one taker, Blitz will have a cache containing 5 live entries and 95 dead ones after things have run for a while.

Important: Each type of Entry is given it's own cache (i.e. there isn't one cache shared across all Entry's of all types). So approximate total memory usage (to get an accurate figure would require estimating garbage requirements etc) is:

memory = 0;
for (X in all Entry types) {
memory = memory + (cache_size * size_of X)
}

memory = memory + Db database cache size

Where Db database cache size is specified in the configuration file under dbCache

Thus in OutOfMemory situations, the correct approach is to reduce entry cache size or the db cache or increase available JVM heap or a combination of the three. Note that in the case of a persistent Blitz, you should also consider enabling log file serialization stream reset by setting the first boolean parameter to the Persistent class constructor (defined as the storageModel in the configuration file) to true.

Note that there is a tool (EntrySizer) in the Blitz distribution (see Extensions in the documentation for your chosen version) which can be used to compute the approximate size of an Entry as it will be stored in Blitz's cache.

Note also that you can specify individual cache sizes per Entry type using EntryConstraint examples of which can be found in the configuration files. A good basic approach to using these constraints would be to set entryReposCacheSize to something small like 256 or 512 and then use the EntryConstraints to allocate bigger caches (e.g. 1024, 4096) to specific Entry types.

In cases where you are submitting Blitz to high load for sustained periods of time and the CPU usage is close to 100%, consider enabling throttling to prevent overflow of internal queues. See eventQueueBound and taskQueueBound in Appendix B - Configuration Variables.

Administration

Blitz supports JoinAdmin, DestroyAdmin, JavaSpaceAdmin and two custom management interfaces (BlitzAdmin and StatsAdmin and, therefore, can be managed by a variety of browser tools.

The first time a Blitz instance is started, it loads it's JINI configuration information such as lookup groups and locators from it's configuration file. These are then stored in a binary metadata file along with the serviceID and various other pieces of runtime information. Future re-starts of the Blitz instance will read the configuration information from the binary metadata file (unless the StorageModel is Transient, in which case all state is lost and the configuration file will be read again). Thus, further configuration changes in respect of JINI state must be done via JoinAdmin. Other non-JINI configuration information can be changed in the configuration file and will take effect the next time the Blitz instance is restarted.

DestroyAdmin::destroy is usually defined to shutdown the service instance and remove all it's persistent state. As a convenience, Blitz provides a configuration variable, compliantDestroy, which can be used to specify whether a Blitz instance should delete or retain it's state when carrying out a destroy request. When compliantDestroy is false Blitz simply shut's down in response to a destroy call. If compliantDestroy is true Blitz will delete all state before shutting down. If compliantDestroy is not specified in the configuration file, the default is to retain state when destroy is invoked.

It is my belief that, as well as destroy, there should be an additional standardized method to trigger a shutdown whilst retaining state. As there is no such standard, the BlitzAdmin interface provides such a method.


Appendix A - Storage Models

As of Blitz 2.0, it is possible to configure a number of different persistence profiles. They are currently:

  1. Persistent - In this mode, Blitz behaves like a fully persistent JavaSpace such as the persistent version of Outrigger.
  2. Transient - (default setting) causes Blitz to act like a disk-backed cache. In this mode, Blitz behaves like the transient version of Outrigger. No logging is performed and, when Blitz is restarted, all state (including Join state etc.) is lost. Memory-only transient implementations can halt with OutOfMemoryError's if they are over-filled. Blitz avoids this problem by swapping to disk when the number of stored Entry's overflows it's available cache space. Obviously, performance will degrade relative to the amount of swapping Blitz is required to perform. When the caches are sufficiently large, Blitz will make minimal use of disk, yielding maximal performance.
  3. TimeBarrierPersistent - provides a performance versus persistence QoS tradeoff. In this mode, changes made more than a certain number of milliseconds ago are guarenteed to be persistent. More recent changes are not guarenteed persistent but may be persistent. This mode provides the developer with a means of balancing persistence needs against performance.

The actual model used is determined by the value of the configuration variable storageModel. The standard configuration file contains example settings for all three modes which should provide reasonable starting points for more precise tuning. For more details on the exact settings for each model see the Javadoc for org.dancres.blitz.config.Persistent, org.dancres.blitz.config.Transient and org.dancres.blitz.config.TimeBarrierPersistent.


Appendix B - Configuration Variables

Basic Setup

JINI-related options

Notify Subsystem

Lease Subsystem

Allows control of leasing operation such as assigning a maximum allowable lease time.

Advanced Setup

Memory Management

Debug Options

Back to Documentation