[weld-commits] Weld SVN: r4232 - api/trunk/cdi/src/main/java/javax/decorator.

weld-commits at lists.jboss.org weld-commits at lists.jboss.org
Fri Oct 23 01:52:26 EDT 2009


Author: gavin.king at jboss.com
Date: 2009-10-23 01:52:26 -0400 (Fri, 23 Oct 2009)
New Revision: 4232

Modified:
   api/trunk/cdi/src/main/java/javax/decorator/Decorates.java
   api/trunk/cdi/src/main/java/javax/decorator/Decorator.java
   api/trunk/cdi/src/main/java/javax/decorator/package-info.java
Log:
javadoc the decorator package

Modified: api/trunk/cdi/src/main/java/javax/decorator/Decorates.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/decorator/Decorates.java	2009-10-22 22:47:10 UTC (rev 4231)
+++ api/trunk/cdi/src/main/java/javax/decorator/Decorates.java	2009-10-23 05:52:26 UTC (rev 4232)
@@ -26,9 +26,62 @@
 import java.lang.annotation.Target;
 
 /**
- * Specifies that an injected field, initializer method parameter or bean
- * constructor parameter of a decorator class is the delegate attribute.
+ * <p>Identifies the delegate injection point of a decorator.</p>
  * 
+ * <pre>
+ * &#064;Decorator 
+ * class TimestampLogger implements Logger { 
+ *    &#064;Decorates &#064;Any Logger logger; 
+ *    ... 
+ * } 
+ * </pre>
+ * <pre>
+ * &#064;Decorator 
+ * class TimestampLogger implements Logger { 
+ *    private Logger logger; 
+ *    
+ *    public TimestampLogger(&#064;Decorates &#064;Debug Logger logger) { 
+ *       this.logger=logger; 
+ *    } 
+ *    ... 
+ * } 
+ * </pre>
+ * 
+ * <p>All decorators have a delegate injection point. A delegate 
+ * injection point is an injection point of the bean class. The 
+ * type and qualifiers of the injection point are called the 
+ * delegate type and delegate qualifiers.</p>
+ * 
+ * <p>The decorator applies to any bean that is eligible for injection 
+ * to the delegate injection point.</p>
+ * 
+ * <p>A decorator must have exactly one delegate injection point. The 
+ * delegate injection point must be an injected field, initializer 
+ * method parameter or bean constructor method parameter.</p>
+ * 
+ * <p>The delegate type of a decorator must implement or extend every 
+ * decorated type. A decorator is not required to implement the delegate 
+ * type.</p>
+ * 
+ * <p>The container injects a delegate object to the delegate injection 
+ * point. The delegate object implements the delegate type and delegates 
+ * method invocations along the decorator stack.</p> 
+ *
+ * <pre>
+ * &#064;Decorator 
+ * class TimestampLogger implements Logger { 
+ *    &#064;Decorates &#064;Any Logger logger; 
+ *    
+ *    void log(String message) {
+ *       logger.log( timestamp() + ": " + message );
+ *    }
+ *    ...
+ * } 
+ * </pre>
+ * 
+ * @see javax.decorator.Decorator &#064;Decorator specifies that a
+ * class is a decorator.
+ * 
  * @author Gavin King
  * @author Pete Muir
  */

Modified: api/trunk/cdi/src/main/java/javax/decorator/Decorator.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/decorator/Decorator.java	2009-10-22 22:47:10 UTC (rev 4231)
+++ api/trunk/cdi/src/main/java/javax/decorator/Decorator.java	2009-10-23 05:52:26 UTC (rev 4232)
@@ -27,8 +27,42 @@
 import javax.enterprise.inject.stereotype.Stereotype;
 
 /**
- * Specifies that a class is a decorator.
+ * <p>Specifies that a class is a decorator.</p>
  * 
+ * <pre>
+ * &#064;Decorator 
+ * class TimestampLogger implements Logger { ... }
+ * </pre>
+ * 
+ * <p>A decorator implements one or more bean types and 
+ * intercepts business method invocations of beans which 
+ * implement those bean types. These bean types are called 
+ * decorated types.</p>
+ * 
+ * <p>A decorator is a managed bean. The set of decorated types 
+ * of a decorator includes all interfaces implemented directly or 
+ * indirectly by the bean class, except for {@link java.io.Serializable}. 
+ * The decorator bean class and its superclasses are not decorated 
+ * types of the decorator. The decorator class may be abstract.</p>
+ * 
+ * <p>Decorators of a session bean must comply with the bean provider 
+ * programming restrictions defined by the EJB specification. 
+ * Decorators of a stateful session bean must comply with the rules 
+ * for instance passivation and conversational state defined by the 
+ * EJB specification.</p>
+ * 
+ * A decorator may be an abstract Java class, and is not required 
+ * to implement every method of every decorated type.
+ *  
+ * The decorator intercepts every method: 
+ * <ul>
+ * <li>declared by a decorated type of the decorator</li>
+ * <li>that is implemented by the bean class of the decorator.</li>
+ * </ul>
+ * 
+ * @see javax.decorator.Decorates &#064;Decorates identifies the 
+ * delegate injection point of a decorator.
+ * 
  * @author Gavin King
  * @author Pete Muir
  */

Modified: api/trunk/cdi/src/main/java/javax/decorator/package-info.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/decorator/package-info.java	2009-10-22 22:47:10 UTC (rev 4231)
+++ api/trunk/cdi/src/main/java/javax/decorator/package-info.java	2009-10-23 05:52:26 UTC (rev 4232)
@@ -1,5 +1,12 @@
+/**
+ * <p>This package contains annotations relating to decorators.</p>
+ * 
+ * <p>Decorators are superficially similar to interceptors, 
+ * but because they directly implement operations with business 
+ * semantics, they are able to implement business logic and, 
+ * conversely, unable to implement the cross-cutting concerns 
+ * for which interceptors are optimized.</p>
+ * 
+ */
 package javax.decorator;
 
-/**
- * The package javax.decorator contains annotations relating to decorators.
- */



More information about the weld-commits mailing list