javax.decorator.package-info Maven / Gradle / Ivy

/*
 * JBoss, Home of Professional Open Source
 * Copyright 2010, Red Hat, Inc., and individual contributors
 * by the @authors tag. See the copyright.txt in the distribution for a
 * full listing of individual contributors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,  
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * Annotations relating to decorators.
 * 
 * A decorator implements one or more bean types and 
 * intercepts business method invocations of 
 * {@linkplain javax.enterprise.inject beans} which 
 * implement those bean types. These bean types are called 
 * decorated types.
 * 
 * A decorator is a managed bean annotated {@link 
 * javax.decorator.Decorator @Decorator}.
 * 
 * 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. Decorators are called 
 * after interceptors.
 * 
 * Decorated types
 * 
 * The set of decorated types of a decorator includes all 
 * bean types of the managed bean that are Java interfaces, 
 * 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.
 * 
 * A decorator intercepts every method:
 * 
 * declared by a decorated type of the decorator
 * that is implemented by the bean class of the decorator.
 * 
 * 
 * A decorator may be an abstract class, and is not required to 
 * implement every method of every decorated type.
 * 
 * Delegate injection points
 * 
 * All decorators have a 
 * {@linkplain javax.decorator.Delegate delegate injection point}.  
 * A delegate injection point is an injection point of the bean 
 * class annotated {@link javax.decorator.Delegate @Delegate}.
 * 
 * The type of the delegate injection point must implement or 
 * extend every decorated type. A decorator is not required to 
 * implement the type of the delegate injection point.
 * 
 * Enabled decorators
 *  
 * By default, a bean archive has no enabled decorators. A 
 * decorator must be explicitly enabled by listing its bean class 
 * under the <decorators> element of the 
 * beans.xml file of the bean archive. The order of the 
 * decorator declarations determines the decorator ordering. 
 * Decorators which occur earlier in the list are called first.
 * 
 * A decorator is bound to a bean if:
 * 
 * 
 * The bean is {@linkplain javax.enterprise.inject eligible for injection} 
 * to the delegate injection point of the decorator.
 * The decorator is enabled in the bean archive of the bean.
 * 
 * 
 * If a managed bean class is declared final, it may not have
 * decorators. If a managed bean has a non-static, non-private, 
 * final method, it may not have any decorator which implements
 * that method.
 * 
 * A decorator instance is a 
 * {@linkplain javax.enterprise.context.Dependent dependent object} 
 * of the object it decorates.
 * 
 * @see javax.enterprise.inject
 * 
 * @see javax.decorator.Decorator
 * @see javax.decorator.Delegate
 * 
 */
package javax.decorator;