Java EE (Java Enterprise Edition) General Discussion

Our software consists of a variety of JMS producers and consumers used to transform and transmit business to business messages on a large scale.

The service nodes do a variety of things, and we've had trouble over the years ensuring every queue-based service clearly identifies the parameters and payload it accepts, so that everyone from programmers to system administrators can easily see what services are available and how they are to be used.

Some have advocated always adding a web service in front of each message-based service to guarantee interface contracts are all well publicized. I think there are reasons to choose web services and reasons to choose message-based services, and am not convinced this is the right answer to address limitations in expressing the design contract for a message-based service. That said, I really like what we've been able to do with self-documenting web services based on annotations, and wonder if there's a conceptual equivalent in message-based software.

What are your best practices for ensuring your message-based services are as self-documenting as your modern web service?

Thanks in advance for your advice!

Edited by: lsamaha on Apr 16, 2012 11:46 AM