1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
<name>Using Util-Classes</name>
<doc-version>$Date: 2003/09/29 21:10:37 $</doc-version>
<author>Matt Albrecht</author>
</head>
<body>
<section name="top">Contents</section>
<OL>
<LI><A HREF="#spi">Service Provider Interface Loading</A></LI>
<LI><A HREF="#chain">Chainable Exceptions</A></LI>
<LI><A HREF="#tparse">Throwable Parsing</A></LI>
<LI><A HREF="#clh">Class Load Helper</A></LI>
<LI><A HREF="#sstore">Singleton Stores</A></LI>
<LI><A HREF="#mstore">Multiple Stores</A></LI>
</OL>
<section name="spi">Service Provider Interface Loading</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The <tt>SPILoader</tt> class knows how to parse a class loader for references
to files under <tt>META-INF/services/<i>classname</i></tt>. Multiple of
these files may be defined per JAR file or directory in the classpath,
so the <tt>SPILoader</tt>
</P>
<P>
The <tt>SPILoader</tt> class is used by the
<tt>net.sourceforge.groboutils.autodoc.v1.AutoDoc</tt> class, so I'll
review how that class uses the <tt>SPILoader</tt> to gain pluggable runtime
loading of services.
</P>
<P>
AutoDoc does not directly reference the SPILoader, but rather uses the
class <tt>SPISingletonStore</tt> to load and handle singleton instances.
This <tt>SPISingletonStore</tt>, in turn, uses the <tt>SPILoader</tt> to
collect the singletons. The singleton store uses the SPI loader with
this bit of code (this.baseClass refers to the class that all service class
implementations must, well, implement):
</P>
<P>
<PRE CLASS="JavaCode"><SPAN CLASS="gutter"> 97:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>
<SPAN CLASS="gutter"> 98:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>
<SPAN CLASS="gutter"> 99:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">/**</SPAN>
<SPAN CLASS="gutterH">100:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">*</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">Add</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">a</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">set</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">of</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">SPIs</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">from</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">the</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">given</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">class</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">loader</SPAN><SPAN CLASS="syntax2">.</SPAN>
<SPAN CLASS="gutter">101:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">*/</SPAN>
<SPAN CLASS="gutter">102:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">public</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax8">void</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax9">addSPI</SPAN>(<SPAN CLASS="syntax125"> </SPAN>ClassLoader<SPAN CLASS="syntax125"> </SPAN>cl<SPAN CLASS="syntax125"> </SPAN>)
<SPAN CLASS="gutter">103:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">throws</SPAN><SPAN CLASS="syntax125"> </SPAN>IOException
<SPAN CLASS="gutter">104:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">{</SPAN>
<SPAN CLASS="gutterH">105:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>SPILoader<SPAN CLASS="syntax125"> </SPAN>spil<SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">=</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">new</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax9">SPILoader</SPAN>(<SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax4">this</SPAN>.baseClass,<SPAN CLASS="syntax125"> </SPAN>cl<SPAN CLASS="syntax125"> </SPAN>);
<SPAN CLASS="gutter">106:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>
<SPAN CLASS="gutter">107:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">while</SPAN><SPAN CLASS="syntax125"> </SPAN>(spil.<SPAN CLASS="syntax9">hasNext</SPAN>())
<SPAN CLASS="gutter">108:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">{</SPAN>
<SPAN CLASS="gutter">109:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax9">addSingleton</SPAN>(<SPAN CLASS="syntax125"> </SPAN>spil.<SPAN CLASS="syntax9">nextProvier</SPAN>()<SPAN CLASS="syntax125"> </SPAN>);
<SPAN CLASS="gutterH">110:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">}</SPAN>
<SPAN CLASS="gutter">111:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">}</SPAN>
<SPAN CLASS="gutter">112:</SPAN><SPAN CLASS="syntax11">}</SPAN>
</PRE>
Thus, the <tt>SPILoader</tt> can be used like an enumeration or iterator.
</P>
<P>
The <tt>SPILoader</tt> finds the files in the <tt>META-INF/services</tt>
directory that has the same name as the service class. It loads each
file found, parses it, and loads the corresponding class. If the
class is assignable to the service class, then it is instantiated with
the default constructor, and returned.
</P>
<P>
Each service file is a text file describing the class names that provide an
implementation of the service class. Each service class must be on its own
line (whitespace is ignored), and must be declared with the fully-qualified
class name that implements the service. Empty lines and lines beginning
with a hash mark ("#") are ignored.
</P>
<P>
Yes, there can be multiple service files for a particular service class!
How? By having each file in a different JAR file which is in the classpath.
So, if someone adds multiple JAR files, each containing its own service
file (and, thus, their own service class implementations), then all will
be returned. Note, however, that JDK 1.1 does not implement this behavior
(it wasn't introduced until JDK 1.2).
</P>
<section name="chain">Chainable Exceptions</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The Chainable Exception classes allow for a non-JDK 1.4+ application to
implement chainable exceptions. Chainable exceptions are exceptions which
"recast" another exception. For example, a common chore in the Apache
Ant tasks goes something like this:
<!--
try {
f = new FileWriter( myFile );
} catch (IOException ioe) {
throw new BuildException( ioe );
}
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter"> 1:</SPAN> <SPAN CLASS="syntax8">try</SPAN> <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 2:</SPAN> f <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">FileWriter</SPAN>( myFile );
<SPAN CLASS="gutter"> 3:</SPAN> <SPAN CLASS="syntax18">}</SPAN> <SPAN CLASS="syntax8">catch</SPAN> (IOException ioe) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 4:</SPAN> <SPAN CLASS="syntax8">throw</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">BuildException</SPAN>( ioe );
<SPAN CLASS="gutterH"> 5:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
</PRE>
Note that the developer wraps the <tt>IOException</tt> inside the
<tt>BuildException</tt>, recasting the exception to a different type. The
<tt>BuildException</tt> class contains logic to store the embedded exception
and display the embedded exception's stack trace on calls to
<tt>BuildException.printStackTrace()</tt>.
</P>
<P>
The Chainable Exception classes has two methodologies available: extend
the <tt>ChainableException</tt> class, or use the
<tt>ChainableExceptionHelper</tt> class to make any exception chainable.
</P>
<P>
Extending the <tt>ChainableException</tt> class is much like extending
an <tt>Exception</tt>:
<!--
public class MyException extends ChainableException {
public MyException() {
super();
}
public MyException( String message ) {
super( message );
}
public MyException( Throwable cause ) {
super( cause );
}
public MyException( Throwable cause, String message ) {
super( message, cause );
}
public MyException( String message, Throwable cause ) {
super( message, cause );
}
}
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter"> 1:</SPAN><SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">class</SPAN> MyException <SPAN CLASS="syntax8">extends</SPAN> ChainableException <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 2:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 3:</SPAN> <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter"> 4:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 5:</SPAN>
<SPAN CLASS="gutter"> 6:</SPAN>
<SPAN CLASS="gutter"> 7:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 8:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter"> 9:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 10:</SPAN>
<SPAN CLASS="gutter"> 11:</SPAN>
<SPAN CLASS="gutter"> 12:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 13:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( cause );
<SPAN CLASS="gutter"> 14:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 15:</SPAN>
<SPAN CLASS="gutter"> 16:</SPAN>
<SPAN CLASS="gutter"> 17:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause, String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 18:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter"> 19:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 20:</SPAN>
<SPAN CLASS="gutter"> 21:</SPAN>
<SPAN CLASS="gutter"> 22:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message, Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 23:</SPAN> <PRE><SPAN CLASS="gutter"> 1:</SPAN><SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">class</SPAN> MyException <SPAN CLASS="syntax8">extends</SPAN> ChainableException <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 2:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 3:</SPAN> <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter"> 4:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 5:</SPAN>
<SPAN CLASS="gutter"> 6:</SPAN>
<SPAN CLASS="gutter"> 7:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 8:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter"> 9:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 10:</SPAN>
<SPAN CLASS="gutter"> 11:</SPAN>
<SPAN CLASS="gutter"> 12:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 13:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( cause );
<SPAN CLASS="gutter"> 14:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 15:</SPAN>
<SPAN CLASS="gutter"> 16:</SPAN>
<SPAN CLASS="gutter"> 17:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause, String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 18:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter"> 19:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 20:</SPAN>
<SPAN CLASS="gutter"> 21:</SPAN>
<SPAN CLASS="gutter"> 22:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message, Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 23:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter"> 24:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 25:</SPAN><SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 26:</SPAN>
</PRE> <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter"> 24:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 25:</SPAN><SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 26:</SPAN>
</PRE>
</P>
<P>
To make your own exception chainable, you simply need to follow the design
of the <tt>ChainableException</tt> class. Below is a simple, non-javadoc
way to make your own:
<!--
import java.io.PrintStream;
import java.io.PrintWriter;
import net.sourceforge.groboutils.util.throwable.v1.IChainableException;
import net.sourceforge.groboutils.util.throwable.v1.ChainableExceptionHelper;
public class MyChainableException extends Exception
implements IChainableException
{
/** @serial */
private ChainableExceptionHelper ceh;
public MyChainableException() {
super();
this.ceh = new ChainableExceptionHelper( this );
}
public MyChainableException( String message ) {
super( message );
this.ceh = new ChainableExceptionHelper( this );
}
public MyChainableException( Throwable cause ) {
super();
this.ceh = new ChainableExceptionHelper( this, cause );
}
public MyChainableException( Throwable cause, String message ) {
this( message, cause );
}
public MyChainableException( String message, Throwable cause ) {
super( message );
this.ceh = new ChainableExceptionHelper( this, cause );
}
public synchronized Throwable getCause() {
return this.ceh.getCause();
}
public synchronized Throwable initCause( Throwable cause ) {
return this.ceh.initCause( cause );
}
public void printStackTrace( PrintStream ps ) {
this.ceh.printStackTrace( ps );
}
public void printStackTrace( PrintWriter pw ) {
this.ceh.printStackTrace( pw );
}
}
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter"> 1:</SPAN><SPAN CLASS="syntax9">import</SPAN> java.io.PrintStream;
<SPAN CLASS="gutter"> 2:</SPAN><SPAN CLASS="syntax9">import</SPAN> java.io.PrintWriter;
<SPAN CLASS="gutter"> 3:</SPAN><SPAN CLASS="syntax9">import</SPAN> net.sourceforge.groboutils.util.throwable.v1.IChainableException;
<SPAN CLASS="gutter"> 4:</SPAN><SPAN CLASS="syntax9">import</SPAN> net.sourceforge.groboutils.util.throwable.v1.ChainableExceptionHelper;
<SPAN CLASS="gutterH"> 5:</SPAN>
<SPAN CLASS="gutter"> 6:</SPAN><SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">class</SPAN> MyChainableException <SPAN CLASS="syntax8">extends</SPAN> Exception
<SPAN CLASS="gutter"> 7:</SPAN> <SPAN CLASS="syntax8">implements</SPAN> IChainableException
<SPAN CLASS="gutter"> 8:</SPAN><SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 9:</SPAN> <SPAN CLASS="syntax3">/**</SPAN><SPAN CLASS="syntax3"> </SPAN><SPAN CLASS="syntax12">@serial</SPAN><SPAN CLASS="syntax3"> </SPAN><SPAN CLASS="syntax3">*/</SPAN>
<SPAN CLASS="gutterH"> 10:</SPAN> <SPAN CLASS="syntax8">private</SPAN> ChainableExceptionHelper ceh;
<SPAN CLASS="gutter"> 11:</SPAN>
<SPAN CLASS="gutter"> 12:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 13:</SPAN> <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter"> 14:</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN> );
<SPAN CLASS="gutterH"> 15:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 16:</SPAN>
<SPAN CLASS="gutter"> 17:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 18:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter"> 19:</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN> );
<SPAN CLASS="gutterH"> 20:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 21:</SPAN>
<SPAN CLASS="gutter"> 22:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 23:</SPAN> <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter"> 24:</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN>, cause );
<SPAN CLASS="gutterH"> 25:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 26:</SPAN>
<SPAN CLASS="gutter"> 27:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( Throwable cause, String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 28:</SPAN> <SPAN CLASS="syntax14">this</SPAN>( message, cause );
<SPAN CLASS="gutter"> 29:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 30:</SPAN>
<SPAN CLASS="gutter"> 31:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( String message, Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 32:</SPAN> <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter"> 33:</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN>, cause );
<SPAN CLASS="gutter"> 34:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH"> 35:</SPAN>
<SPAN CLASS="gutter"> 36:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax8">synchronized</SPAN> Throwable <SPAN CLASS="syntax6">getCause</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 37:</SPAN> <SPAN CLASS="syntax8">return</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">getCause</SPAN>();
<SPAN CLASS="gutter"> 38:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 39:</SPAN>
<SPAN CLASS="gutterH"> 40:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax8">synchronized</SPAN> Throwable <SPAN CLASS="syntax6">initCause</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 41:</SPAN> <SPAN CLASS="syntax8">return</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">initCause</SPAN>( cause );
<SPAN CLASS="gutter"> 42:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 43:</SPAN>
<SPAN CLASS="gutter"> 44:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">void</SPAN> <SPAN CLASS="syntax6">printStackTrace</SPAN>( PrintStream ps ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutterH"> 45:</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">printStackTrace</SPAN>( ps );
<SPAN CLASS="gutter"> 46:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 47:</SPAN>
<SPAN CLASS="gutter"> 48:</SPAN> <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">void</SPAN> <SPAN CLASS="syntax6">printStackTrace</SPAN>( PrintWriter pw ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter"> 49:</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">printStackTrace</SPAN>( pw );
<SPAN CLASS="gutterH"> 50:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter"> 51:</SPAN><SPAN CLASS="syntax18">}</SPAN>
</PRE>
The claass implements IChainableException (to broadcast its JDK 1.4+
compatible chainable methods), and delegates method calls to the
<tt>ChainableExceptionHelper</tt> class.
</P>
<section name="tparse">Throwable Parsing</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
By using the
<tt>net.sourceforge.groboutils.util.throwable.v1.ThrowableParser</tt>
class, you can discover the details of the stack history of a
<tt>Throwable</tt> in any JDK.
</P>
<P>
For instance, if you need to know which method of a specific class
invoked the current method, you could perform:
<!--
String classToLookFor = c.getName();
Throwable t = new Throwable();
t.fillInStackTrace();
ThrowableParser tp = new ThrowableParser( t );
StackTraceLineParser stlp = tp.next();
String method = null;
int lineNumber = -1;
while (method == null && stlp != null) {
if (classToLookFor.equals( stlp.getClassName() )) {
method = stlp.getMethodName();
lineNumber = stlp.getLineNumber();
}
}
if (method != null) {
System.out.println( "This method was called by class "+
classToLookFor+" in method "+method+" on line "+
lineNumber+"." );
} else {
System.out.println( "Class "+classToLookFor+
" didn't call this method." );
}
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter"> 8:</SPAN>String classToLookFor <SPAN CLASS="syntax18">=</SPAN> c.<SPAN CLASS="syntax6">getName</SPAN>();
<SPAN CLASS="gutter"> 9:</SPAN>Throwable t <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">Throwable</SPAN>();
<SPAN CLASS="gutterH">10:</SPAN>t.<SPAN CLASS="syntax6">fillInStackTrace</SPAN>();
<SPAN CLASS="gutter">11:</SPAN>ThrowableParser tp <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ThrowableParser</SPAN>( t );
<SPAN CLASS="gutter">12:</SPAN>StackTraceLineParser stlp <SPAN CLASS="syntax18">=</SPAN> tp.<SPAN CLASS="syntax6">next</SPAN>();
<SPAN CLASS="gutter">13:</SPAN>String method <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN>;
<SPAN CLASS="gutter">14:</SPAN><SPAN CLASS="syntax10">int</SPAN> lineNumber <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax18">-</SPAN><SPAN CLASS="syntax5">1</SPAN>;
<SPAN CLASS="gutterH">15:</SPAN><SPAN CLASS="syntax8">while</SPAN> (method <SPAN CLASS="syntax18">=</SPAN><SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN> <SPAN CLASS="syntax18">&</SPAN><SPAN CLASS="syntax18">&</SPAN> stlp <SPAN CLASS="syntax18">!</SPAN><SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN>) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">16:</SPAN> <SPAN CLASS="syntax8">if</SPAN> (classToLookFor.<SPAN CLASS="syntax6">equals</SPAN>( stlp.<SPAN CLASS="syntax6">getClassName</SPAN>() )) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">17:</SPAN> method <SPAN CLASS="syntax18">=</SPAN> stlp.<SPAN CLASS="syntax6">getMethodName</SPAN>();
<SPAN CLASS="gutter">18:</SPAN> lineNumber <SPAN CLASS="syntax18">=</SPAN> stlp.<SPAN CLASS="syntax6">getLineNumber</SPAN>();
<SPAN CLASS="gutter">19:</SPAN> <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">20:</SPAN><SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">21:</SPAN>
<SPAN CLASS="gutter">22:</SPAN><SPAN CLASS="syntax8">if</SPAN> (method <SPAN CLASS="syntax18">!</SPAN><SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN>) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">23:</SPAN> System.out.<SPAN CLASS="syntax6">println</SPAN>( <SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax13">This</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">method</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">was</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">called</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">by</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">class</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax18">+</SPAN>
<SPAN CLASS="gutter">24:</SPAN> classToLookFor<SPAN CLASS="syntax18">+</SPAN><SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">in</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">method</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax18">+</SPAN>method<SPAN CLASS="syntax18">+</SPAN><SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">on</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">line</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax18">+</SPAN>
<SPAN CLASS="gutterH">25:</SPAN> lineNumber<SPAN CLASS="syntax18">+</SPAN><SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax13">.</SPAN><SPAN CLASS="syntax13">"</SPAN> );
<SPAN CLASS="gutter">26:</SPAN><SPAN CLASS="syntax18">}</SPAN> <SPAN CLASS="syntax8">else</SPAN> <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">27:</SPAN> System.out.<SPAN CLASS="syntax6">println</SPAN>( <SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax13">Class</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax18">+</SPAN>classToLookFor<SPAN CLASS="syntax18">+</SPAN>
<SPAN CLASS="gutter">28:</SPAN> <SPAN CLASS="syntax13">"</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">didn't</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">call</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">this</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">method.</SPAN><SPAN CLASS="syntax13">"</SPAN> );
<SPAN CLASS="gutter">29:</SPAN><SPAN CLASS="syntax18">}</SPAN>
</PRE>
</P>
<section name="clh">Class Load Helper</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The class
<tt>net.sourceforge.groboutils.util.classes.v1.ClassLoadHelper</tt>
aids the developer by providing convienent methods that can:
<UL>
<LI>
return a class object without worrying about trapping the various
exceptions;
</LI>
<LI>
create a new object from the default constructor without trapping
the various exceptions;
</LI>
<LI>
create an object based on a property in a
<tt>java.util.Hashtable</tt> that declares the class to instantiate;
and
</LI>
<LI>
easily load resources, including multiple resources of the same
name.
</LI>
</UL>
The design wraps many JDK 1.2 and above calls into JDK 1.1-safe invocations.
</P>
<section name="sstore">Singleton Stores</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The singleton pattern can be extremely powerful, conserving memory
requirements and hiding implementation details behind a factory-like
mechanism.
</P>
<P>
However, most implementations do not allow for robust access. There exist
some needs to swap out one singleton for another. Let's say, for example,
that an application has a utility class for loading class files from a URL
and dynamically loading them in the VM. If this application was written
with JDK 1.1, it had to manually download the class files (possibly JAR
files), load them into a specialized class loader, then return the new
class. However, when JDK 1.2 was released, those users could take advantage
of the URLClassLoader class. The utility could be rewritten to use a
factory/proxy pattern, but that could break backwards compatibility.
Instead, the application could swap out the singleton with a JDK 1.1 or
JDK 1.2 implementation.
</P>
<P>
The GroboUtils Singleton Store class
(<tt>net.sourceforge.groboutils.util.classes.v1.SingletonStore</tt>)
allows for a class to contain a static reference to the Store, then allow
access to replace the Singleton in the store with another instance.
The SPISingletonStore does just this.
</P>
<section name="mstore">Multiple Stores</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The GroboUtils Multiple Store class
(<tt>net.sourceforge.groboutils.util.classes.v1.AbstractMultipleStore</tt>),
just like the <A HREF="#sstore">Singleton Stores</A>, allow for a central
location to manage the singleton, but the Multiple Store class allows for
several such instances to be stored, and new instances to be added as
needed.
</P>
</body>
</document>
|
