I generally agree with Sreeram's points. However, optional
Attributes can be troublesome in an API.
AMX handles properties with the PropertiesAccess interface. Any AMX
MBean with properties implements this interface.
Simple properties
For a simple property (call it 'Bart'), you would write (for example):
final String propertyName = "Bart";
final String value = serverConfig.getPropertyValue( propertyName );
serverConfig.setPropertyValue( propertyName, "bite_me" );
serverConfig.removeProperty( propertyName );
An optional Attribute (instead of a property)
Now consider what happens if you turn an optional property into an
Attribute:
// must return null or throw an Exception
final String value = serverConfig.getBart();
// Add or change "Bart", it can previously exist or not exit
serverConfig.setBart( "bite_me" );
// Remove "Bart". The "magic value" 'null' is used to indicate removal;
// there is no removeAttribute() method (we could add one I suppose).
serverConfig.setBart( null );
In the above example, the API "works" only because we can use the
magic value 'null'. If we have any boolean or int values, they can't
be handled; we'd have to use Boolean or Integer to make the
distinction (or throw an exception).
Multi-valued Atrributes or properties
Multi-valued properties become a headache for the user:
final String value = serverConfig.getPropertyValue
( "BartsExpressions" );
// list contains {"bite_me, oh_man, homer"}, comma-separated
final String[] values = value.split( "," ); // what about ", ", ",
", etc?!!!
serverConfig.setPropertyValue( "BartsExpressions", stringArrayToString
( values ) );
The above isn't exactly user-friendly, and carries certain risks.
For example, what is the separator between items? Is the separator
legal within an item, and if so, how is it escaped? Are there
utility routines to parse and stringify the values? How do you add
just one value, or remove just one? What if the values can contain
unicode?
In short, multi-valued items are a serious headache for a
programmer. Any time such a value is incepted, there needs to be
very clear documentation as to what the legal values are, what the
separator is, how it's escaped, whether "," and ", " are the same,
and, ideally, utility routines to do everything. Unfortunately, in
implementing AMX, I found that this crucial documentation step was
either unspecified or ambiguous in some cases, and not necessarily
consistent in all cases (it might be, but there's no easy way to find
out!).
At least with properties, there is an opportunity to divide the
namespace up to make this job easier. For example, the property
could be either of these two things:
BartsExpressions=bite_me, oh_man, homer"
OR
BartsExpressions.favorite="bite_me"
BartsExpressions.daily="oh_man"
BartsExpressions.theMan="homer"
If we settled on such a standard, then it would be possible to add
a method to PropertiesAccess like:
Map<String,String> m = serverConfig.getPropertyMap
( "BartsExpressions" );
and then write:
Set<String> values = m.values(); // names can be ignored, or used as
desired
serverConfig.addProperty( "BartsExpressions.sister", "Lisa" );
serverConfig.removeProperty( "BartsExpressions.1", "bite_me" );
serverConfig.removeProperties( "BartsExpressions" );
The above are intended as an example; there might be a better way.
Summary
A key issue going forward is thinking through how the choice of
properties vs Attributes affects usability for a programmer,
especially with multi-valued items.
Lloyd Chambers
On Aug 24, 2006, at 11:26 AM, Sreeram Duvur wrote:
> 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
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>