-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
/
mutableexception.xml
250 lines (219 loc) · 7.35 KB
/
mutableexception.xml
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
<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://maven.apache.org/XDOC/2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 https://maven.apache.org/xsd/xdoc-2.0.xsd">
<head>
<title>MutableException</title>
</head>
<body>
<section name="MutableException">
<p>Since Checkstyle 3.2</p>
<subsection name="Description" id="Description">
<p>
Ensures that exception classes (classes with names conforming to some pattern
and explicitly extending classes with names conforming to other
pattern) are immutable, that is, that they have only final fields.
</p>
<p>
The current algorithm is very simple: it checks that all members of
exception are final. The user can still mutate an exception's instance
(e.g. Throwable has a method called <code>setStackTrace</code>
which changes the exception's stack trace). But, at least, all information
provided by this exception type is unchangeable.
</p>
<p>
Rationale: Exception instances should represent an error
condition. Having non-final fields not only allows the state to be
modified by accident and therefore mask the original condition but
also allows developers to accidentally forget to set the initial state.
In both cases, code catching the exception could draw incorrect
conclusions based on the state.
</p>
</subsection>
<subsection name="Properties" id="Properties">
<div class="wrapper">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
<th>since</th>
</tr>
<tr>
<td>extendedClassNameFormat</td>
<td>Specify pattern for extended class names.</td>
<td><a href="../../property_types.html#Pattern">Pattern</a></td>
<td><code>"^.*Exception$|^.*Error$|^.*Throwable$"</code></td>
<td>6.2</td>
</tr>
<tr>
<td>format</td>
<td>Specify pattern for exception class names.</td>
<td><a href="../../property_types.html#Pattern">Pattern</a></td>
<td><code>"^.*Exception$|^.*Error$|^.*Throwable$"</code></td>
<td>3.2</td>
</tr>
</table>
</div>
</subsection>
<subsection name="Examples" id="Examples">
<p id="Example1-config">
To configure the check:
</p>
<source>
<module name="Checker">
<module name="TreeWalker">
<module name="MutableException"/>
</module>
</module>
</source>
<p id="Example1-code">Example:</p>
<source>
class Example1 extends Exception {
private int code; // OK, class name doesn't match with default pattern
public Example1() {
code = 1;
}
}
class FirstException extends Exception {
private int code; // violation
public FirstException() {
code = 2;
}
}
class FirstThrowable extends Throwable {
final int code; // OK
String message; // violation
public FirstThrowable(int code, String message) {
this.code = code;
this.message = message;
}
}
class FirstBadException extends java.lang.Exception {
int code; // violation
public FirstBadException(int code) {
this.code = code;
}
}
</source>
<p id="Example2-config">
To configure the check so that it checks for class name that ends
with 'Exception':
</p>
<source>
<module name="Checker">
<module name="TreeWalker">
<module name="MutableException">
<property name="format" value="^.*Exception$"/>
</module>
</module>
</module>
</source>
<p id="Example2-code">Example:</p>
<source>
class Example2 extends Exception {
private int code; // OK, class name doesn't match with given pattern
public Example2() {
code = 1;
}
}
class SecondException extends Exception {
private int code; // violation
public SecondException() {
code = 2;
}
}
class SecondThrowable extends Throwable {
final int code; // OK, class name doesn't match with given pattern
String message; // OK, class name doesn't match with given pattern
public SecondThrowable(int code, String message) {
this.code = code;
this.message = message;
}
}
class SecondBadException extends java.lang.Exception {
int code; // violation
public SecondBadException(int code) {
this.code = code;
}
}
</source>
<p id="Example3-config">
To configure the check so that it checks for type name that is used in
'extends' and ends with 'Throwable':
</p>
<source>
<module name="Checker">
<module name="TreeWalker">
<module name="MutableException">
<property name="extendedClassNameFormat" value="^.*Throwable$"/>
</module>
</module>
</module>
</source>
<p id="Example3-code">Example:</p>
<source>
class Example3 extends Exception {
private int code; // OK, extended class name doesn't match with given pattern
public Example3() {
code = 1;
}
}
class ThirdException extends Exception {
private int code; // OK, extended class name doesn't match with given pattern
public ThirdException() {
code = 2;
}
}
class ThirdThrowable extends Throwable {
final int code; // OK
String message; // violation
public ThirdThrowable(int code, String message) {
this.code = code;
this.message = message;
}
}
class ThirdBadException extends java.lang.Exception {
int code; // OK, extended class name doesn't match with given pattern
public ThirdBadException(int code) {
this.code = code;
}
}
</source>
</subsection>
<subsection name="Example of Usage" id="Example_of_Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Aconfig%20path%3A**%2Fcheckstyle-checks.xml+repo%3Acheckstyle%2Fcheckstyle+MutableException">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Violation Messages" id="Violation_Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fdesign%20path%3A**%2Fmessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22mutable.exception%22">
mutable.exception
</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="../../config.html#Custom_messages">see the documentation</a>
to learn how to.
</p>
</subsection>
<subsection name="Package" id="Package">
<p>
com.puppycrawl.tools.checkstyle.checks.design
</p>
</subsection>
<subsection name="Parent Module" id="Parent_Module">
<p>
<a href="../../config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
</body>
</document>