Author: pete.muir(a)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.htm... + * 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