Mercurial > hg > blitz_stable

comparison docs/tools.html @ 0:3dc0c5604566

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial checkin of blitz 2.0 fcs - no installer yet.
author Dan Creswell <dan.creswell@gmail.com>
date Sat, 21 Mar 2009 11:00:06 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:3dc0c5604566
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <head>
4 <title>Tools Guide</title>
5
6
7 <meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
8
9 <link rel="stylesheet" type="text/css" href="ssl.css">
10
11 </head>
12
13 <body style="background-color: rgb(255, 255, 255);">
14
15 <a name="tools"></a>
16 <h1>Tools Guide</h1>
17
18 <h3>Dashboard</h3>
19
20 Used to monitor a Blitz JavaSpaces instance as it runs. You can
21 graphically access statistics such as memory usage, instance counts and
22 number of active transactions. Graphing options are also provided,
23 where appropriate.
24 Dashboard supports lookup of a Blitz JavaSpaces instance via multicast
25 discovery (just specify the space name) or unicast discovery (specify
26 the lookup service host and the space name):
27 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/dashboard.jar:lib/stats.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.dash.StartDashBoard dancres<br></pre>
28
29 or
30 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath lib/dashboard.jar:lib/stats.jar:/home/dan/jini/jini2_1/lib/jsk-lib.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.dash.StartDashBoard rogue:4160 dancres<br></pre>
31
32 <p><b>NOTE:</b> The provision of stats can be
33 controlled programmatically or via the configuration file. Currently,
34 for Dashboard to provide full information, you must have enabled
35 appropriate options in the configuration file - e.g.:</p>
36
37 <pre>import org.dancres.blitz.stats.Switch;<br>import org.dancres.blitz.stats.OpSwitch;<br>import org.dancres.blitz.stats.InstanceSwitch;<br><br>org.dancres.blitz {<br> stats = new Switch[] {new OpSwitch(OpSwitch.ALL_TYPES,<br> OpSwitch.TAKE_OPS, true),<br> new OpSwitch(OpSwitch.ALL_TYPES, OpSwitch.READ_OPS, true),<br> new OpSwitch(OpSwitch.ALL_TYPES, OpSwitch.WRITE_OPS, true),<br> new InstanceSwitch(InstanceSwitch.ALL_TYPES, true)};<br>}<br></pre>
38
39 <hr align="center" size="3" width="70%">
40 <h3>SyncAndShutdown</h3>
41
42 Used to shutdown a Blitz instance and sync all it's state to disk. This
43 tool works with all <code>StorageModel</code>s including <code>Transient</code>.
44 <code>SyncAndShutdown</code> supports lookup of a Blitz
45 JavaSpaces instance via multicast discovery (just specify the space
46 name) or unicast discovery (specify the lookup service host and the
47 space name):
48 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.SyncAndShutdown dancres<br></pre>
49
50 or
51 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.SyncAndShutdown rogue:4160 dancres<br></pre>
52
53 <p><b>NOTE:</b>The shutdown of a Blitz instance may
54 result in the loss of state associated with transactions active (not
55 commited) at the time of shutdown. Typically, entries written under
56 such transactions will be lost and any takes performed will not have
57 been completed such that the <code>Entry</code>s will
58 remain in the databases. All <code>Entry</code>s untouched
59 by transactions are <em>guarenteed</em> to be undamaged.</p>
60
61 <hr align="center" size="3" width="70%">
62 <h3>DumpEntries</h3>
63
64 Used to dump the contents of a Blitz instance's databases after it's
65 been shutdown with <code>SyncAndShutdown</code>. This tool
66 will work in combination with <code>SyncAndShutdown</code>
67 against even a transient Blitz instance.
68 <p>Basic usage of <code>DumpEntries</code> requires
69 that you specify the blitz configuration file of the Blitz instance
70 whose contents you wish to display.</p>
71
72 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:dbjava/je.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.DumpEntries config/blitz.config<br></pre>
73
74 <p><code>DumpEntries</code> will display not only
75 Blitz internal information but will also attempt to unpack the Entry
76 instance and display it using the relevant codebase. To disable this
77 feature (perhaps because the codebase is not available) run <code>DumpEntries</code>
78 as follows:</p>
79
80 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all -Dnounpack=true<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:dbjava/je.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.DumpEntries config/blitz.config<br></pre>
81
82 <p><b>NOTE:</b> Dumping the contents of a Blitz
83 instance should <em>only</em> be done after it's been
84 shutdown using <code>SyncAndShutdown</code>. <code>DumpEntries</code>
85 is strictly read-only and, therefore, cannot damage the contents of the
86 databases.</p>
87
88 <hr align="center" size="3" width="70%">
89 <h3>HotBackup (experimental)</h3>
90
91 Used to make a hot backup of a blitz instance. Arguments are a
92 directory to backup to and either a space name or an LUS host URL and
93 spacename. Note that the specified directory must be available to the
94 machine on which the Blitz instance is running.
95 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.HotBackup /home/dan/src/jini/space/backups dancres<br></pre>
96
97 or
98 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.HotBackup /home/dan/src/jini/space/backups rogue:4160 dancres<br></pre>
99
100 <p><b>Note:</b> the specified directory should be
101 empty otherwise the backup will be refused.</p>
102
103 <hr align="center" size="3" width="70%">
104 <h3>Entry Cleaning (experimental)</h3>
105
106 <p>The <code>Cleanup</code> tool remotely connects
107 to a specified Blitz instance causing it to clean out all old Entry's.
108 The process performs the following steps:</p>
109
110 <ol>
111
112 <li>Kill all outstanding blocking matches</li>
113
114 <li>Abort all outstanding transactions</li>
115
116 <li>Delete all Entry's</li>
117
118 <li>Checkpoint (to ensure all deletes are commited to disk)</li>
119
120 <li>Delete all repositories</li>
121
122 </ol>
123
124 <p><code>Cleanup</code> supports lookup of a Blitz
125 JavaSpaces instance via multicast discovery (just specify the space
126 name) or unicast discovery (specify the lookup service host and the
127 space name):</p>
128
129 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.Cleanup dancres<br></pre>
130
131 or
132 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.Cleanup rogue:4160 dancres<br></pre>
133
134 <hr align="center" size="3" width="70%">
135 <h3>Manual Lease Reaping</h3>
136
137 Used to cause Blitz to perform a single lease-reaping pass clearing out
138 all dead Entrys. Ensure that <code>leaseReapInterval</code>
139 is set to <code>LeaseReaper.MANUAL_REAP</code>. Failure to
140 set this option will cause manual lease cleanup to fail.
141 This tool works with all <code>StorageModel</code>s
142 including <code>Transient</code>. <code>RequestReap</code>
143 supports lookup of a Blitz JavaSpaces instance via multicast discovery
144 (just specify the space name) or unicast discovery (specify the lookup
145 service host and the space name):
146 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.RequestReap dancres<br></pre>
147
148 or
149 <pre>cd /home/dan/src/jini/space<br>java -Djava.security.policy=config/policy.all<br> -classpath /home/dan/jini/jini2_1/lib/jsk-lib.jar:lib/blitz.jar:/home/dan/jini/jini2_1/lib/jsk-platform.jar:/home/dan/jini/jini2_1/lib/sun-util.jar<br> org.dancres.blitz.tools.RequestReap rogue:4160 dancres<br></pre>
150
151 <hr align="center" size="3" width="70%">
152 <h3>Log Dumping</h3>
153
154 <p>This tool can be used offline in a similar fashion to
155 DumpEntries, to examine Blitz's activity logs allowing the user to form
156 a picture of exactly what operations were performed during a particular
157 run. Log Dumping can only be used for persistent instances and includes
158 details of lease renewals, notification registrations, transactions and
159 read/write/take.</p>
160
161 <p>The tool requires a single argument which is the directory
162 specified in the <code>logDir</code> variable of the
163 relevant <code>.config</code>. Here's an example:</p>
164
165 <pre>java -Djava.security.policy=config/policy.all<br> -classpath /Users/dan/jini/jini2_1/lib/jsk-lib.jar:/Users/dan/jini/jini2_1/lib/jsk-platform.jar:lib/blitz.jar<br> org.prevayler.implementation.SnapshotPrevaylerImpl<br> /Users/dan/blitz-install/logs/<br></pre>
166
167 <p>Note that normally, only successful operations are logged but
168 it can sometimes be useful to also see failed reads and takes. By
169 default Blitz does not log these but you can enable it by adding <code>logSearches
170 = new Boolean(true);</code> to your blitz configuration file.
171 &nbsp;You may also wish to enable logging of instance counts by
172 adding <code>logCounts = new Boolean(true);</code> to your blitz configuration file.</p>
173
174 <hr align="center" size="3" width="70%">
175 <h3>Lookup Settings Import</h3>
176
177 <p>In accordance with the Jini specifications, Blitz will only read the <code>initial</code>* lookup parameters from it's configuration file on first boot (in transient mode this means the parameters are re-read every boot, whilst persistent modes will deem first boot to occur when there's no previous log or database state present).</p>
178
179 <p>Under various circumstances it can be desirable to reset Blitz's internal lookup settings from a configuration file post first-boot. This <code>ReconfigLookup</code> tool is used to perform this task providing support to selectively import settings from a specified configuration file.</p>
180
181 <p><code>ReconfigLookup</code> accepts a path to a configuration file followed by one or more flags indicating which lookup settings to import. These flags are <code>-groups</code>, <code>-attrs</code>, <code>-locators</code>. An example usage of this tool appears below:</p>
182
183 <pre>java -Djava.security.policy=config/policy.all<br> -classpath /Users/dan/jini/jini2_1/lib/jsk-lib.jar:/Users/dan/jini/jini2_1/lib/jsk-platform.jar:lib/blitz.jar:dbjava/je.jar<br> org.dancres.blitz.tools.ReconfigLookup <br> /Users/dan/blitz/config/blitz.config <br> -groups -attrs -locators<br></pre>
184
185 </body>
186 </html>