Some General Conventions to be Followed for Making Something an Attribute/Property Element in the Domain DTD

• 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.

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 (sduv@dev.java.net)