Better semantics for BeanDeploymentArchive, add a top level deploymen…

…t concept

git-svn-id: http://anonsvn.jboss.org/repos/weld/ri/trunk@2930 1c488680-804c-0410-94cd-c6b725194a0e

spi/src/main/java/org/jboss/webbeans/bootstrap/spi/BeanDeploymentArchive.java

@@ -19,42 +19,47 @@
 import java.net.URL;
 import java.util.List;
 
+import org.jboss.webbeans.bootstrap.api.Service;
 import org.jboss.webbeans.ejb.spi.EJBModule;
 
 /**
  * Represents a CDI bean deployment archive.
  * 
- * A bean deployment archive is any library jar, EJB jar or rar archive with a
- * META-INF/beans.xml file, any WEB-INF/classes directory in war with a
- * WEB-INF/beans.xml, or any directory in the classpath with a
- * META-INF/beans.xml.
+ * A deployment archive is any library jar, library directory, EJB jar, rar
+ * archive or any war WEB-INF/classes directory contained in the Java EE
+ * deployment (as defined in the Java Platform, Enterprise Edition (Java EE)
+ * Specification, v6, Section 8.1.2).
  * 
- * For an application deployed as an ear, all library jars, EJB jars, rars and
- * war WEB-INF/classes directories should be searched.
+ * TODO Java SE definition of a deployment archive
  * 
- * For an application deployed as a war, all library jars and the
- * WEB-INF/classes directory should be searched.
+ * A bean deployment archive is any deployment archive with a META-INF/beans.xml
+ * file, or for a war, with a WEB-INF/beans.xml.
  * 
- * The container is allowed to specify archives as {@link BeanDeploymentArchive}
- * even if no beans.xml is present.
+ * The container is allowed to specify a deployment archive as
+ * {@link BeanDeploymentArchive} even if no beans.xml is present (for example, a
+ * container could define a deployment archive with container specific metadata
+ * to be a bean deployment archive).
  * 
  * @see EJBModule
+ * @see Deployment
  * 
  * @author Pete Muir
  * 
  */
-public interface BeanDeploymentArchive
+public interface BeanDeploymentArchive extends Service
 {
 
    /**
-    * Get the ordered transitive closure of modules which are accessible to this
-    * module. The order will be used both in bean discovery and resolution.
+    * Get the ordered bean deployment archives which are accessible to this bean
+    * deployment archive and adjacent to it in the deployment archive graph.
+    * 
+    * The bean deployment archives will be processed in the order specified.
     * 
     * Circular dependencies will be detected and ignored by the container
     * 
-    * @return the ordered transitive closure
+    * @return the ordered accessible bean deployment archives
     */
-   public List<BeanDeploymentArchive> getBeanDeploymentArchiveClosure();
+   public List<BeanDeploymentArchive> getBeanDeploymentArchives();
 
    /**
     * Gets all classes in the bean deployment archive

spi/src/main/java/org/jboss/webbeans/bootstrap/spi/Deployment.java

@@ -0,0 +1,81 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2008, Red Hat Middleware LLC, and individual contributors
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,  
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jboss.webbeans.bootstrap.spi;
+
+import java.util.List;
+
+import org.jboss.webbeans.ejb.spi.EJBModule;
+
+/**
+ * Represents a deployment of a CDI application.
+ * 
+ * Web Beans will request the bean archive deployment structure during the bean
+ * discovery initialization step. After this step, CDI allows users to define
+ * bean's programmatically, possibly with bean classes from a deployment archive
+ * which is currently not a bean deployment archive. Web Beans will request the
+ * {@link BeanDeploymentArchive} for each programmatically using
+ * {@link #loadBeanDeploymentArchive(Class)}. If any unknown
+ * {@link BeanDeploymentArchive}s are loaded, before Web Beans proceeds to
+ * validating the deployment, the bean archive deployment structure will
+ * re-requested.
+ * 
+ * For an application deployed as an ear to a Java EE container, all library
+ * jars, EJB jars, rars and war WEB-INF/classes directories should be searched,
+ * and the bean deployment archive structure built.
+ * 
+ * For an application deployed as a war to a Java EE or Servlet container, all
+ * library jars and the WEB-INF/classes directory should be searched, and the
+ * bean deployment archive structure built.
+ * 
+ * TODO Java SE structure
+ * 
+ * @see BeanDeploymentArchive
+ * @see EJBModule
+ * 
+ * @author Pete Muir
+ * 
+ */
+public interface Deployment
+{
+
+   /**
+    * Get the bean deployment archives which are accessible by this deployment
+    * and adjacent to it in the deployment archive graph.
+    * 
+    * The bean deployment archives will be processed in the order specified.
+    * 
+    * Circular dependencies will be detected and ignored by the container
+    * 
+    * @return the ordered accessible bean deployment archives
+    * 
+    */
+   public List<BeanDeploymentArchive> getBeanDeploymentArchives();
+
+   /**
+    * Load the {@link BeanDeploymentArchive} containing the given class.
+    * 
+    * If the deployment archive containing the given class is not currently a
+    * bean deployment archive, it should be added to the bean deployment archive
+    * graph and returned. If the deployment archive is currently a bean
+    * deployment archive it should be returned.
+    * 
+    * @param beanClass the bean class to load
+    * @return the {@link BeanDeploymentArchive} containing the bean class
+    */
+   public BeanDeploymentArchive loadBeanDeploymentArchive(Class<?> beanClass);
+
+}

spi/src/main/java/org/jboss/webbeans/ejb/spi/EJBModule.java

@@ -17,6 +17,7 @@
 package org.jboss.webbeans.ejb.spi;
 
 import org.jboss.webbeans.bootstrap.spi.BeanDeploymentArchive;
+import org.jboss.webbeans.bootstrap.spi.Deployment;
 
 /**
  * Represents an EJB bean deployment archive.
@@ -26,6 +27,9 @@
  * {@link BeanDeploymentArchive}; the Java EE container is responsible for
  * identifying EJB bean deployment archives.
  * 
+ * @see BeanDeploymentArchive
+ * @see Deployment
+ * 
  * @author Pete Muir
  * 
  */