CVS: plexus-container-new/src/java/org/apache/plexus/embed Embedder.java,1.1,1.2

Update of /cvsroot/plexus/plexus-container-new/src/java/org/apache/plexus/embed
In directory eng.werken.com:/tmp/cvs-serv308/src/java/org/apache/plexus/embed

Modified Files:
	Embedder.java 
Log Message:
Enhanced the Embedder so that a client can get ahold of the container
instance if needed (e.g. a command line application for example).  
 
 - Added start() and stop() methods so clients have the option of
   starting and stopping the container.

 - Added explicit state checking to the public methods as we want users
   to clearly understand the usage of this API.

 - Added javadoc to all of the public methods.

I'm not entirely sure of how others will embed this in their apps, but I
at least got it working for my simple plexus tutorial app that I wrote.



Index: Embedder.java
===================================================================
RCS file: /cvsroot/plexus/plexus-container-new/src/java/org/apache/plexus/embed/Embedder.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- Embedder.java	24 May 2003 22:25:04 -0000	1.1
+++ Embedder.java	25 May 2003 16:38:15 -0000	1.2
@@ -10,48 +10,173 @@
 import java.io.FileNotFoundException;
 
 /**
+ * <tt>Embedder</tt> enables a client to embed Plexus into their
+ * application with a minimal amount of work.  The basic usage is
+ * as follows:
+ * <br/>
+ * <pre>
+ *     Embedder embedder = new Embedder();
+ *     embedder.setConfiguration("/plexus.xml");
+ *     embedder.addContextValue("plexus.home", ".");
+ *     embedder.start();
  *
+ *     PlexusContainer container = embedder.getContainer();
+ *     [do stuff with container]
+ *
+ *     embedder.stop();
+ * </pre>
+ * <br/>
  * 
  * @author <a href="mailto:[email protected]">Jason van Zyl</a>
- *
+ * @author <a href="[email protected]">Pete Kazmier</a>
  * @version $Id$
  */
 public class Embedder
 {
-    /** Plexus Container. */
-    private PlexusContainer container;
     /** Configuration resource or file. */
     private String configuration;
+    
+    /** Plexus Container. */
+    private PlexusContainer container;
 
-    public void Embedder()
-        throws Exception
+    /** Flag to indicate embedder has been started. */
+    private boolean embedderStarted = false;
+
+    /** Flag to indicate embedder has been stopped. */
+    private boolean embedderStopped = false;
+
+    /**
+     * Default constructor.
+     */
+    public Embedder()
     {
         container = new DefaultPlexusContainer();
     }
 
+    /**
+     * Gets the <tt>PlexusContainer</tt> that was started by the
+     * embedder.
+     *
+     * @return The <tt>PlexusContainer</tt> that was started.
+     * @throws IllegalStateException If the embedder has not already
+     * been started.
+     */
+    public PlexusContainer getContainer()
+    {
+        if (!embedderStarted)
+        {
+            throw new IllegalStateException("Embedder must be started");
+        }
+        
+        return container;
+    }
+    
+    /**
+     * Set the configuration for the <tt>PlexusContainer</tt>.  This
+     * configuration can either be a file or a resource in the
+     * classpath.
+     *
+     * @param configuration A file or resource in the classpath that
+     * contains the configuration for the <tt>PlexusContainer</tt>.
+     * @throws IllegalStateException If the embedder has already been
+     * started or stopped.
+     */
     public void setConfiguration( String configuration )
     {
+        if (embedderStarted || embedderStopped)
+        {
+            throw new IllegalStateException(
+                "Embedder has already been started");
+        }
+        
         this.configuration = configuration;
     }
 
+    /**
+     * Add a value to the <tt>PlexusContainer</tt>'s context.
+     *
+     * @param key The key for the context value.
+     * @param value The value to be inserted.
+     * @throws IllegalStateException If the embedder has already been
+     * started or stopped.
+     */
     public void addContextValue( Object key, Object value )
     {
+        if (embedderStarted || embedderStopped)
+        {
+            throw new IllegalStateException(
+                "Embedder has already been started");
+        }
+
         container.addContextValue( key, value );
     }
 
-    public void run()
+    /**
+     * Start the <tt>PlexusContainer<tt>.  This container can then be
+     * fetched via <tt>getContainer</tt> for use by clients.
+     *
+     * @throws Exception If there was an error starting the container.
+     * @throws IllegalStateException If the embedder has already been
+     * started, or if its already been stopped.  The embedder cannot
+     * be restarted.
+     */
+    public void start()
         throws Exception
     {
-        container.setConfigurationResource( new InputStreamReader( findConfigurationInputStream()  ) );
+        if (embedderStarted)
+        {
+            throw new IllegalStateException("Embedder already started");
+        }
+
+        if (embedderStopped)
+        {
+            throw new IllegalStateException("Embedder cannot be restarted");
+        }
+
+        container.setConfigurationResource(
+            new InputStreamReader( findConfigurationInputStream() ) );
         container.initialize();
         container.start();
+        embedderStarted = true;
+    }
+
+    /**
+     * Stop the <tt>PlexusContainer</tt>.  Once the container has been
+     * stopped, it cannot be restarted.
+     *
+     * @throws Exception If there was a problem stopping the container.
+     * @throws IllegalStateException If the embedder has not been
+     * started, or if its already been stopped.
+     */
+    public void stop()
+        throws Exception
+    {
+        if (!embedderStarted)
+        {
+            throw new IllegalStateException("Embedder not started");
+        }
+
+        if (embedderStopped)
+        {
+            throw new IllegalStateException("Embedder already stopped");
+        }
+
         container.dispose();
+        embedderStarted = false;
+        embedderStopped = true;
+    }
+    
+    public void run()
+        throws Exception
+    {
+        start();
+        stop();
     }
 
     private InputStream findConfigurationInputStream()
     {
-        InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream( configuration );
-
+        InputStream is = getClass().getResourceAsStream(configuration);
+        
         if ( is == null )
         {
             try