[weld-commits] Weld SVN: r4268 - api/trunk/cdi/src/main/java/javax/enterprise/inject.

[weld-commits at lists.jboss.org]

Author: gavin.king at jboss.com
Date: 2009-10-24 12:42:54 -0400 (Sat, 24 Oct 2009)
New Revision: 4268

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/inject/Stereotype.java
Log:
doc @Stereotype

Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/Stereotype.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/Stereotype.java	2009-10-24 16:42:34 UTC (rev 4267)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/Stereotype.java	2009-10-24 16:42:54 UTC (rev 4268)
@@ -25,8 +25,97 @@
 import java.lang.annotation.Target;
 
 /**
- * Specifies that an annotation type is a stereotype.
+ * <p>Specifies that an annotation type is a stereotype.</p>
  * 
+ * <p>In many systems, use of architectural patterns produces 
+ * a set of recurring bean roles. A stereotype allows a framework 
+ * developer to identify such a role and declare some common metadata 
+ * for beans with that role in a central place.</p>
+ * 
+ * <p>A stereotype encapsulates any combination of:</p>
+ * 
+ * <ul>
+ * <li>a default scope, and</li>
+ * <li>a set of interceptor bindings.</li>
+ * </ul>
+ * 
+ * <p>The default scope of a stereotype is defined by annotating the 
+ * stereotype with a scope type. A stereotype may declare at most one 
+ * scope. If a bean explicitly declares a scope, any default scopes 
+ * declared by its stereotypes are ignored.</p> 
+ * 
+ * <pre>
+ * &#064;RequestScoped
+ * &#064;Stereotype 
+ * &#064;Target(TYPE) 
+ * &#064;Retention(RUNTIME) 
+ * public &#064;interface Action {}
+ * </pre>
+ * 
+ * <p>The interceptor bindings of a stereotype are defined by annotating 
+ * the stereotype with the interceptor binding types. A stereotype may 
+ * declare zero, one or multiple interceptor bindings. An interceptor binding 
+ * declared by a stereotype is inherited by any bean that declares that 
+ * stereotype.</p>
+ * 
+ * <pre>
+ * &#064;RequestScoped 
+ * &#064;Secure 
+ * &#064;Transactional 
+ * &#064;Stereotype 
+ * &#064;Target(TYPE) 
+ * &#064;Retention(RUNTIME) 
+ * public &#064;interface Action {}
+ * </pre>
+ * 
+ * <p>A stereotype may also specify that:</p>
+ * 
+ * <ul>
+ * <li>all beans with the stereotype have defaulted bean EL names, or 
+ * that</li>
+ * <li>all beans with the stereotype are alternatives.</li>
+ * </ul>
+ * 
+ * <p>A stereotype may declare an empty 
+ * {@link javax.inject.Named &#064;Named} annotation, which specifies 
+ * that every bean with the stereotype has a defaulted name when a 
+ * name is not explicitly specified by the bean.</p>
+ * 
+ * <pre>
+ * &#064;RequestScoped 
+ * &#064;Named 
+ * &#064;Secure 
+ * &#064;Transactional 
+ * &#064;Stereotype 
+ * &#064;Target(TYPE) 
+ * &#064;Retention(RUNTIME) 
+ * public &#064;interface Action {}
+ * </pre>
+ * 
+ * <p>A stereotype may declare an 
+ * {@link javax.enterprise.inject.Alternative &#064;Alternative}
+ * annotation, which specifies that every bean with the stereotype is 
+ * an alternative.</p>
+ * 
+ * <pre>
+ * &#064;Alternative 
+ * &#064;Stereotype 
+ * &#064;Target(TYPE) 
+ * &#064;Retention(RUNTIME) 
+ * public &#064;interface Mock {}
+ * </pre>
+ * 
+ * <p>A stereotype may declare other stereotypes. Stereotype 
+ * declarations are transitive. A stereotype declared by a second 
+ * stereotype is inherited by all beans and other stereotypes that 
+ * declare the second stereotype.</p>
+ * 
+ * <p>A bean may declare zero, one or multiple stereotypes, by
+ * applying the stereotype annotation to the bean class or producer 
+ * method or field.</p>
+ * 
+ * @see javax.enterprise.inject.Model the built-in stereotype <tt>&#064;Model</tt>
+ * 
  * @author Pete Muir
  * @author Gavin King
  */