Here are some conventions we have applied over the years in evolving
domain.xml
* Prefer ATTLIST entry for any configuration that you expect to be
supported by documentation, CLI, GUI and MBeans
* Properties are permitted when you cannot predict the configuration up
front, such as for a JDBC Driver
* Unstable/Experimental features are supposed to use only properties.
* Sometimes, property may be added late in the release cycle for a late
bug fix or feature. The module lead is expected to
promote it to an attribute in a subsequent release. The earlier property
support may disappear over time. In the interface
stability taxonomy a specific <property> element is unstable.
* Create a holding element if a group of attributes can be clumped
together for sharing or just for cleaner separation.
* #IMPLIED or #REQUIRED must be specified. In case of #IMPLIED we would
like to see the default value explicitly
in the DTD, if possible. Sometimes this is not possible (computed default)
The above rules with consistent naming conventions has been quite
effective so far. Lets try to stick to it.
It is true that some elements are bloating with a lot of attributes,
like in this case. I don't think we anticipated it.
Using optional new attributes is still the best way forward. Creating a
sub-element of jdbc-connection-pool is
also a good second choice. Adding naming conventions to properties or
adding another element called
<connection-pool-property> seemed like the wrong things to do.
Also if we find ourselves documenting a property over multiple releases
and the feature is no longer experimental,
we should ask that it be promoted to a documented attribute.
Sreeram