On Fri, May 22, 2015 at 12:31 PM, Darran Lofthouse <darran.lofthouse@jboss.com> wrote:

The first option is to do it all by convention and have no shared
constants, the down side of this is we now need to document this and
keep the document maintained. A document would also make it hard in the
future to flag certain capabilities as deprecated if preferred
alternatives are made available.

Well, deprecated can be done on two levels, one is compile time, the other runtime.

and at runtime it is easy to add feedback that certain capability is deprecated.

The second option would be to just define the Strings somewhere and use
Javadoc to specify if the capability is dynamic and it's service type.

That one sounds ok, but you still need central place with constants, even if just for compile.

The third option is defining the string and RuntimeCapability instances
in a central place so they can both be referenced as needed.

I don't like this one at all, I know it was in initial design of capabilities
and it was the single thing I disliked the most.

so IMO, either #1 or #2 is fine, but lest avoid #3 if possible.