[webbeans-commits] Webbeans SVN: r3149 - ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi.

[webbeans-commits at lists.jboss.org]

Author: pete.muir at jboss.org
Date: 2009-07-23 08:36:32 -0400 (Thu, 23 Jul 2009)
New Revision: 3149

Modified:
   ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/Deployment.java
Log:
Add examples and more details about logical deployment archives

Modified: ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/Deployment.java
===================================================================
--- ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/Deployment.java	2009-07-23 08:55:04 UTC (rev 3148)
+++ ri/trunk/spi/src/main/java/org/jboss/webbeans/bootstrap/spi/Deployment.java	2009-07-23 12:36:32 UTC (rev 3149)
@@ -23,6 +23,25 @@
 /**
  * Represents a deployment of a CDI application.
  * 
+ * <h3>Background</h3>
+ * 
+ * <p>
+ * Java EE defines a series of accessibility rules for classloading, which CDI
+ * extends to cover bean resolution. For example a bean in the war can inject a
+ * bean in an ejb-jar, but not vice-versa.
+ * </p>
+ * 
+ * <p>
+ * These rules are defined via the MANIFEST.MF <a
+ * href="http://java.sun.com/javase/6/docs/technotes/guides/extensions/"
+ * >Extension Mechanism Architecture</a> and <a
+ * href="http://java.sun.com/javase/6/docs/technotes/guides/jar/jar.html">JAR
+ * File Specification</a>.
+ * </p>
+ * 
+ * <h3>Deployment structure representation</h3>
+ * 
+ * <p>
  * 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
@@ -32,21 +51,62 @@
  * {@link BeanDeploymentArchive}s are loaded, before Web Beans proceeds to
  * validating the deployment, the bean archive deployment structure will
  * re-requested.
+ * </p>
  * 
+ * <p>
+ * The BeanDeploymentArchive tree represents the "logical structure" of the
+ * deployment; Given two archives A and B, which have a transitive closure of
+ * accessible archives A' and B', it allowable for the the archives A & B to be
+ * represented as a single BeanDeploymentArchive, assuming that A' and B' are
+ * bi-directionally accessible.
+ * </p>
+ * 
+ * <p>
  * 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.
+ * </p>
  * 
+ * <p>
  * 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.
+ * </p>
  * 
- * TODO Java SE structure
+ * <p>
  * For an application deployed in the SE environment, all library jars and
  * classpath directories should be searched, and the bean deployment archive
- * structure built. A single, logical deployment archive will be built for
- * all beans and beans.xml files found on the classpath.
+ * structure built. A single, logical deployment archive will be built for all
+ * beans and beans.xml files found on the classpath.
+ * </p>
  * 
+ * <h3>A Java EE example</h3>
+ * 
+ * <p>
+ * Given an ejb-module A (not as part of an ear), an ear B (containing an
+ * ejb-jar C which uses the standard mechanism to reference module A, libraries
+ * F bundled in /lib, and a war D which references module C), and a war E (which
+ * references module A and bundles libraries G in /WEB-INF/lib) all deployed.
+ * </p>
+ * 
+ * <p>
+ * War E would have be able to resolve beans from ejb module A, libraries G, as
+ * well as other app server libraries. Furthermore, any libraries in G will be
+ * able to resolve beans in other libraries G as well as in ejb module A and war
+ * E. Ejb module A will not be able to resolve beans in war E or libraries G. It
+ * would be legal to represent any libraries G as a single logical
+ * BeanDeploymentArchive, also incorportating classes in war E.
+ * </p>
+ * 
+ * <p>
+ * War D would be able to resolve beans from from ejb module C, module A
+ * (transitively via C), libraries F, as well as other app server libraries. Ejb
+ * module C can resolve beans in libraries F as well as module A, but not beans
+ * in War D. Ejb module A cannot resolve beans in libraries F, module A or war
+ * D. It would be legal to represent libraries F as a single logical
+ * BeanDeploymentArchive.
+ * </p>
+ * 
  * @see BeanDeploymentArchive
  * 
  * @author Pete Muir