Author: gavin.king(a)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. - */