svn commit: r1084034 - /ofbiz/trunk/framework/base/src/org/ofbiz/base/container/Container.java

[adrianc]

Author: adrianc
Date: Tue Mar 22 00:14:11 2011
New Revision: 1084034

URL: http://svn.apache.org/viewvc?rev=1084034&view=rev
Log:
Container.java JavaDocs - no functional change.

Modified:
    ofbiz/trunk/framework/base/src/org/ofbiz/base/container/Container.java

Modified: ofbiz/trunk/framework/base/src/org/ofbiz/base/container/Container.java
URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/base/src/org/ofbiz/base/container/Container.java?rev=1084034&r1=1084033&r2=1084034&view=diff
==============================================================================
--- ofbiz/trunk/framework/base/src/org/ofbiz/base/container/Container.java (original)
+++ ofbiz/trunk/framework/base/src/org/ofbiz/base/container/Container.java Tue Mar 22 00:14:11 2011
@@ -19,30 +19,44 @@
 package org.ofbiz.base.container;
 
 /**
- * Container - Interface for containers
+ * An OFBiz container. A container can be thought of as a background process.
+ *
+ * <p>
+ * When OFBiz starts, the main thread will create the <code>Container</code> instance and
+ * then call the container's <code>init</code> method. If the method returns without
+ * throwing an exception the container will be added to a list of initialized containers.
+ * After all instances have been created and initialized, the main thread will call the
+ * <code>start</code> method of each container in the list. When OFBiz shuts down, a
+ * separate shutdown thread will call the <code>stop</code> method of each container.
+ * Implementations should anticipate asynchronous calls to the methods by different
+ * threads.
+ * </p>
+ *
  */
 public interface Container {
 
-    /** Initialize the container
+    /** Initialize the container.
      *
-     * @param args args from calling class
-     * @param configFile Location of master OFBiz configuration file
-     * @throws ContainerException
+     * @param args Command-line arguments.
+     * @param configFile Location of the configuration file used to load this container.
+     * @throws ContainerException If an error was encountered. Throwing this exception
+     * will halt container loading, so it should be thrown only when other containers
+     * might depend on this one.
      */
     public void init(String[] args, String configFile) throws ContainerException;
 
     /**
-     * Start the container
+     * Start the container process.
      *
-     * @return true if server started
-     * @throws ContainerException
+     * @return <code>true</code> if the process started.
+     * @throws ContainerException If an error was encountered.
      */
     public boolean start() throws ContainerException;
 
     /**
-     * Stop the container
+     * Stop the container process.
      *
-     * @throws ContainerException
+     * @throws ContainerException If an error was encountered.
      */
     public void stop() throws ContainerException;
 }