7:36 a.m.
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