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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- Content Stylesheet for Site -->
<!-- start the processing -->
<!-- ====================================================================== -->
<!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
<!-- Main Page Section -->
<!-- ====================================================================== -->
<html>
<head>
<link rel="stylesheet" href="./css/base.css"/>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<title>Tuscany - Tuscany Java Coding Guidelines</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td align='LEFT'><td align="left">
<a href="http://incubator.apache.org/tuscany/"><img src="./images/tuscanylogo_candidate2.jpg" alt="Tuscany" border="0" height="32" width="120"/></a>
</td>
</td>
<td align='LEFT'><td width="80%" align="left" valign="bottom" bgcolor="#ffffff">
<font color="#625972" size="+3" face="arial,helvetica,sanserif">
<b><bannertitle>Tuscany Java Coding Guidelines</bannertitle></b>
</font>
</td>
</td>
</tr>
</table>
<hr noshade="" size="1"/>
<table border="0" cellspacing="0">
<tr>
<td> <a href="./index.html">Home</a>
</td>
<td> <a href="./sca_index.html">SCA</a>
</td>
<td> <a href="./sdo_index.html">SDO</a>
</td>
<td> <a href="./das_index.html">DAS</a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4">
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td width="20%" valign="top" nowrap="true">
<!-- ============================================================ -->
<p><strong>General</strong></p>
<ul>
<li> <a href="./index.html">Home</a>
</li>
<li> <a href="./news.html">News</a>
</li>
<li> <a href="./documentation.html">Documentation</a>
</li>
<li> <a href="./license.html">License</a>
</li>
<li> <a href="http://www.apache.org/" target="_blank">ASF</a>
</li>
<li> <a href="./downloads.html">Downloads</a>
</li>
</ul>
<p><strong>Community</strong></p>
<ul>
<li> <a href="./get-involved.html">Get Involved</a>
</li>
<li> <a href="./mail-lists.html">Mailing Lists</a>
</li>
<li> <a href="./faq.html">FAQ</a>
</li>
<li> <a href="./issue-tracking.html">Issue Tracking</a>
</li>
<li> <a href="http://wiki.apache.org/ws/Tuscany" target="_blank">Wiki</a>
</li>
<li> <a href="http://apache-tuscany.blogspot.com" target="_blank">Blog</a>
</li>
</ul>
<p><strong>Development</strong></p>
<ul>
<li> <a href="http://wiki.apache.org/ws/Tuscany/TuscanyJava/Roadmap" target="_blank">Road Map / TODO</a>
</li>
<li> <a href="./source-code.html">Source Code</a>
</li>
<li> <a href="./java-projects.html">Java projects</a>
</li>
<li> <a href="./cpp-projects.html">C++ projects</a>
</li>
</ul>
</td>
<td width="80%" align="left" valign="top">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#726982">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Tuscany Java Coding Guidelines"><strong>Tuscany Java Coding Guidelines</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<ol>
<li><a href="#Indentation">Indentation</a></li>
<li><a href="#Exception Handling">Exception Handling</a></li>
<li><a href="#Package Naming"> Package Naming</a></li>
<li><a href="#Logging">Logging</a></li>
</ol>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#726982">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Indentation"><strong>Indentation</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
We follow Sun's coding standard rules which are pretty common in Java. We have also discussed to adopt a tool that would scan the code to make sure it is in the right format. More information will be added once that discussion is final.
</p>
<p>
<script type="text/javascript">linkNewWindow('http://java.sun.com/docs/codeconv/','http://java.sun.com/docs/codeconv/');</script>
</p>
<p>
<script type="text/javascript">linkNewWindow('http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html','http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html');</script>
</p>
<p>
Please use 4 characters indentation and do not use tabs.
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#726982">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Exception Handling"><strong>Exception Handling</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
In general Exceptions should be designed thinking what the catcher of exception would likely do with the exception. There are three types of exceptions.
</p>
<ul>
<li>
Code Exception: Can be handled at some level of the call stack.
</li>
<li>
User Exception: Problem can be handled by a user of the system, for example an Administrator.
</li>
<li>
Assertion Exception: Problem remedied by developer fixing a bug in the code
</li>
</ul>
<p>
<span style="font-size: 14pt;">
Code Exceptions
</span>
</p>
<p>
There are two types of code exceptions, checked and unchecked exceptions. A checked exception would be thrown when the code cannot handle a specific situation. In this case it is expected for the caller to handle this exception in one of the following ways: 1) handle the exception, 2) re-throw it to its caller, 3) change it to another exception that makes sense to its caller. In general, code exceptions should be checked exceptions. They should be named based on what happened, rather than based on who is throwing the exception. If the exception is well named, it should be possible for the exception to be present on signatures at several levels of a call stack and still make sense (e.g. ServiceUnavailableException).
</p>
<p>
Throw unchecked exceptions if the exception is a programming error or system failure and cannot be handled by the caller (RuntimeException).
</p>
<p>
<span style="font-size: 14pt;">
User Exceptions
</span>
</p>
<p>
User Exceptions are exceptions that signal a problem that needs to be handled by the user of the system, for example an administrator. Text of the message that is carried with the exception needs to be clear in order to help the user to debug the problem. For example a stack trace is not useful information for a user. It is important to catch user type exceptions and add meaningful context to build a message that is useful.
</p>
<p>
A base UserException class can have an array of messages, rather than just one message. For example, code that parses an SCA subsystem file might have a rethrow that just adds "While parsing the xyz subsystem file". This message could probably not be generated by the code that discovered the problem (say an XML parsing problem), so a combination of the original message (e.g. "Missing end tag") and the higher level message ("while parsing the xyz subsystem file") are both necessary to know what happened. Naturally it can be any number of levels deep.
</p>
<p>
The handling code for a user exception will somehow notify a user of the message and then possibly go on.
In a server, user exceptions can often be divided according to the fault type.
</p>
<ul>
<li>
Client fault: This is typically generated by the client code that sends the incoming message (e.g. SOAP faults). In this case, the message needs to be reported back to the client code in a format appropriate to the client. ClientExecption should be used to relay exceptions that occur on the client side.
</li>
<li>
Code or configuration fault: In this case, only a vague "problem occured here" message should be sent to the client and the real exception message should be logged and/or sent to an administrator.
</li>
</ul>
<p>
The remaining user exceptions are typically problems with configuration or the environment. Some of them will be severe enough that the entire application needs to be brought down, while others could be handled by just logging the problem and going on. This difference implies that there needs to be a different exception type. In the case of session-scoped services, the problem is likely to require that the instance of the service be put into an error state (like paused). This is because subsequent messages for the service have been sent on the assumption that the previous message actually gets processed. If some configuration error prevents a session-scoped service from handling a single message, all future (async) messages for that service instance should be queued up so they can be processed once the problem has been solved.
</p>
<p>
<span style="font-size: 14pt;">
Assertion Exceptions
</span>
</p>
<p>
Assertion exceptions are exceptions that result from a bug in Tuscany and as such are also intended to be solved by the developers. In these cases the message isn't nearly as important, since the stack trace provides valuable context. If an assertion exception occurs little can be known about the state of the server. If we wanted to be safe we would say that assertion exceptions always bring down the entire server. However, we could play it a little looser and say that assertion exceptions only bring down the application in which they are discovered.
</p>
<p>
<span style="font-size: 14pt;">
Guidelines
</span>
</p>
<p>
The following are a set of guidelines based on the above exception philosophy:
</p>
<p>
1. Checked vs. unchecked exceptions
Unchecked exceptions should be used when an error condition is not recoverable. Checked exceptions thrown by third party libraries that are not recoverable should be wrapped in unchecked exceptions rather than being propagated up the call stack. For example, an IOException raised when reading a file might be wrapped in an unchecked LoadException containing the name of the file. Unchecked must always be Javadoced and declared in the throws clause of a method.
</p>
<p>
2. Assertion exceptions should use the standard JDK assert facilities
</p>
<p>
3. Any exception thrown to user code must extend the appropriate Exception as defined by the specification. This will typically be a runtime Exception.
</p>
<p>
4. No other Exceptions should be thrown to user code. Each user API method should catch any internal exceptions and wrap them in the applicable Exception defined by the specification. Internal exceptions must ultimately extend either TuscanyException or TuscanyRuntimeException.
</p>
<p>
4. When possible, create clear package exception hierarchies
In most cases, packages should have a clear exception hierarchy with abstract root checked and unchecked exceptions which more specific concrete exceptions extend. Declaring the root package exceptions abstract avoids code throwing exceptions which are too general. Creating an exception hierarchy allows client code using a particular package to choose the level of exception handling granularity (which in turn simplifies the client code by avoiding unwieldy try..catch clauses).
</p>
<p>
5. Preserve all stack trace information and the original exception
Exceptions must always preserve the stack trace and original exception except under special circumstances. When wrapping exceptions to propagate, never modify the stack trace and always include the caught exception as the cause.
</p>
<p>
6. Only include local information pertinent to the failure
For I18N, contextual information stored in the Exception should not be localized. It should comprise only data pertaining to the cause, such as the name of the artifact as above, or a key that can be used by the top level exception handler. This is needed because the locale used to render the exception may be completely different from the locale used by the code raising the exception. For example, an exception may be thrown on a system whose default locale is German, logged to the system log in English but displayed to the end user in French, Japanese, whatever their native language is.
</p>
<p>
7. For exceptions that require contextual information from various code layers, either wrap exceptions or create exceptions that can accept additional context as they are propagated up the call stack.
</p>
<p>
If a failure requires information from multiple levels, e.g. there was an error setting property X on component Y in module Zdo one of the following. If the initial exception should be wrapped as it is propagated (e.g. the exception occurs at a library boundary), add additional context information in the wrapping exception(s). If the initial exception can be propagated, include methods for adding additional context information as the exception is rethrown up the stack. For example, the previous failure scenario could result in the following exception handling strategy:
A component property is configured with an invalid integer type
The property value parsing code attempts to load an integer value using parseInt(), resulting in a NumberFormatException
NumberFormatException is wrapped in an InvalidParameterException (IPE) containing the name of the property.
IPE extends a more general ConfigException, which has setters for adding additional context information such as component and module names
As the IPE is thrown up the stack, the component and module parsers provide additional context information.
The configuration loader then wraps the IPE in a ConfigLoadExeption and provides the source from which the configuration is being loaded.
The UI being used to load the configuration reports the error to the user and displays the appropriate contextual information
</p>
<p>
8. getMessage() must return unformatted context info. If the Exception contains multiple context fields they should be surrounded in square brackets and separated by commas, e.g. "[ property X, component Y, module Z ]"
</p>
<p>
9. Do not override the behaviour of Throwable.toString() and Throwable.printStackTrace()
</p>
<p>
10. The java.lang.Exception base class is Serializable so all subclasses must provide a serial UID. Any context fields must be Serializable and should be defined in the base java namespace for JDK1.4.
</p>
<p>
11. Exceptions that wrap other Exceptions should ensure that any wrapped Exception can be deserialized in a client environment. This may require providing a custom writeObject method to extract any context information from the wrapped Exception during serialization; at a minimum the message should be preserved.
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#726982">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Package Naming"><strong>Package Naming</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
TBD
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#726982">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Logging"><strong>Logging</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
TBD
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
</td>
</tr>
</table>
<hr noshade="" size="1"/>
<table border="0" width="100%" cellspacing="0">
<tr>
<td><img src="./images/apache-incubator-logo.png" alt="Apache Incubator Logo"/></td>
<td class="disclaimer">
<em>Copyright © 2006, The Apache Software Foundation</em><br/>
Apache Tuscany is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Web Services PMC.
Incubation is required of all newly accepted projects until a further review indicates that the infrastructure,
communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.
While incubation status is not necessarily a reflection of the completeness or stability of the code,
it does indicate that the project has yet to be fully endorsed by the ASF.
</td>
</tr>
</table>
</body>
</html>
<!-- end the processing -->
|
