I'm interested in an SOP (service oriented platform) for some of the work that I'm currently doing. It would make my life much easier if there was a container with which I could register my services that would take care of lifecycle concerns.

After doing a little research to see what's going on out there I started looking at JBoss's org.jboss.system.Service interface as well as their org.jboss.deployment.Deployer. This is the Service interface:

/**
 * The Service interface.
 */
public interface Service
{
   /**
    * create the service, do expensive operations etc 
    */
   void create() throws Exception;
   
   /**
    * start the service, create is already called
    */
   void start() throws Exception;
   
   /**
    * stop the service
    */
   void stop();
   
   /**
    * destroy the service, tear down 
    */
   void destroy();
}

(The above code is available under the LGPL.)

Do you notice anything missing from the above interface? What's the threading contract?!? Should start() start its own thread if necessary? Does the container provide a thread to start() so that it can manage the lifecycle better and ensure that a faulty start() would not block the entire infrastructure? Etc. After a few minutes of code splunking I discovered that it's just simply undefined (the assumption is that it's the first case).

I'll spare everyone the rant and I will just say: Please document the complete contract on important interfaces. When you write javadocs, ask yourself what would someone need to know that has never seen the code. Attempt to place yourself into their shoes and you will likely end up with more useful javadocs.