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.
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
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.
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
.
/home/dan/src/jini/space
/home/dan/jini/jini2_1
/home/dan/jini/jini2_1/jini-start
yakuza
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.
cd /home/dan/jini/jini2_1/jini-start/example/scriptsYou may also find it useful to run the ServiceBrowser so you can check that things are performing as expected:
./urun httpd
./urun jeri-transient-reggie
./urun jeri-transient-mahalo
./urun jeri-browserNow we must start a codebase server for Blitz:
./urun httpd -port 8081 -dir /home/dan/src/jini/space/libIf 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
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/Note that the default configuration files expect to create a log for the shared activation group in
java -Djava.security.policy=config/policy.all -jar /home/dan/jini/jini2_1/lib/start.jar config/start-act-blitz21.config
/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
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.
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.
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.
As of Blitz 2.0, it is possible to configure a number of different persistence profiles. They are currently:
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.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
.
Allows control of leasing operation such as assigning a maximum allowable lease time.
org.dancres.blitz.tools.RequestReap
by setting this to org.dancres.blitz.lease.LeaseReaper.MANUAL_REAP
org.dancres.blitz.config.EntryConstraint
.org.dancres.blitz.remote.user.ColocatedAgent
.JavaSpaceAdmin
and JavaSpace05
update their working match sets with entry's written after the set was created. Note enabling this can mean that one never reaches the end of the match set or that the match set overflows memory if it fills faster than a client empties it.org.dancres.blitz.config.EntryConstraint
.Level
entrys in it's configuration file. This allows a developer to use the
standard logger configuration approach when appropriate.org.dancres.blitz.stats
.
This information is processed by Dashboard.