jakarta.decorator.package-info Maven / Gradle / Ivy
Show all versions of jakarta.enterprise.cdi-api Show documentation
/*
* Copyright 2010, Red Hat, Inc., and 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 jakarta.enterprise.inject beans} which
* implement those bean types. These bean types are called
* decorated types.
*
*
*
* A decorator is a managed bean annotated {@link
* jakarta.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 jakarta.decorator.Delegate delegate injection point}.
* A delegate injection point is an injection point of the bean
* class annotated {@link jakarta.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 jakarta.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 jakarta.enterprise.context.Dependent dependent object}
* of the object it decorates.
*
*
* @see jakarta.enterprise.inject
*
* @see jakarta.decorator.Decorator
* @see jakarta.decorator.Delegate
*
*/
package jakarta.decorator;