<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
Subsystem Development Conventions
</h3>
<span style="margin-bottom: 10px;">
created by <a href="http://community.jboss.org/people/jason.greene">Jason Greene</a> in <i>JBoss AS7 Development</i> - <a href="http://community.jboss.org/docs/DOC-17346">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>There are a number of common problems that a subsystem developer will run into. This document is an attempt to convey the best recommended practices and common conventions that other subsystems follow. Following these will make it easier for UI tools to be developed since everything works according to a similar set of rules.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Use Resources Over Complex Attributes</h3><p>It is much easier for UI tools to handle a small set of simple operations (add/remove/write) with simple attributes than it is to handle a monolothic resource with complex nested attributes. It also offers more flexibility in runtime updates. For example, it may be possible to increase the max thread size of a pool without restarting and replacing the entire pool. The rule of thumb is to keep creating resources until you hit primitives. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>There is of course exceptions. For example,If the configuration contains an ordered list of which there is no unique name, a resource does not fit well. In this case a complex list type is unavoidable. However in such a scenario a set of "helper" operations should be created (e.g. add-foo).</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In some cases it may not be clear how to model a nested child as a resource because it does not have a key->value name which is required. When this happens, you will need to come up with a new naming convention that fits the key/value model yet is still based on the original notion. For example a subsystem that has a foo, and a foo-expanded can change those names to be something like foo=classic and foo=expanded.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Make All Attributes Writable</h3><p>Anything that can be edited in an xml file <strong>MUST</strong> be writable at runtime. It is possible, however, that modifying such a value can not be done "hot" at runtime, in which case forcing the server to reload or restart is the appropriate action (See ReloadRequiredWriteAttributeHandler)</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Make ADD Smart, Don't Expose "Activate" Operations</h3><p>The common problem is that during boot, or during a composite operation, the parent ADD happens BEFORE a child node ADD. Therefore it's runtime handler is called first. The proper way to deal with this situation is to have the parent add operation add a new "step" runtime handler to make the actual changes. This step will automatically run after all of the ones before it (the children), and so it will be able to read the various child resources that are needed.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Use SimpleResourceDefinition and *AttrributeDefinition</h3><p>These automate a large portion of validation and description handling, which makes the subsystem less error prone and quicker to develop.</p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-17346">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss AS7 Development at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>