jakarta.enterprise.inject.spi.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.
*/
/**
* The portable extension integration SPI.
*
* A portable extension may integrate with the container by:
*
*
* - Providing its own beans, interceptors and decorators to the
* container
* - Injecting dependencies into its own objects using the
* dependency injection service
* - Providing a context implementation for a custom scope
* - Augmenting or overriding the annotation-based metadata with
* metadata from some other source
*
*
* The BeanManager object
*
* Portable extensions sometimes interact directly with the container
* via programmatic API call. The interface
* {@link jakarta.enterprise.inject.spi.BeanManager} provides operations
* for obtaining contextual references for beans, along with many other
* operations of use to portable extensions.
*
* Container lifecycle events
*
* During the application initialization process, the container fires
* a series of {@linkplain jakarta.enterprise.event events}, allowing
* portable extensions to integrate with the container initialization
* process. Observer methods of these events must belong to
* {@linkplain jakarta.enterprise.inject.spi.Extension extensions} declared
* in META-INF/services.
*
* Lifecycle events include
* {@link jakarta.enterprise.inject.spi.BeforeBeanDiscovery},
* {@link jakarta.enterprise.inject.spi.AfterBeanDiscovery},
* {@link jakarta.enterprise.inject.spi.AfterDeploymentValidation} and
* {@link jakarta.enterprise.inject.spi.BeforeShutdown}.
*
* Interfaces representing enabled beans
*
* The interfaces
* {@link jakarta.enterprise.inject.spi.Bean},
* {@link jakarta.enterprise.inject.spi.Decorator},
* {@link jakarta.enterprise.inject.spi.Interceptor} and
* {@link jakarta.enterprise.inject.spi.ObserverMethod}
* define everything the container needs to manage instances of
* a bean, interceptor, decorator or observer method.
*
* An instance of Bean exists for every
* {@linkplain jakarta.enterprise.inject enabled bean}. A portable
* extension may add support for new kinds of beans by implementing
* Bean, observing the event
* {@link jakarta.enterprise.inject.spi.AfterBeanDiscovery} event
* {@linkplain jakarta.enterprise.inject.spi.AfterBeanDiscovery#addBean(Bean)
* registering beans} with the container. An instance of
* ObserverMethod exists for every
* {@linkplain jakarta.enterprise.event observer method} of every
* enabled bean. A portable extension may add observers by implementing
* ObserverMethod and
* {@linkplain jakarta.enterprise.inject.spi.AfterBeanDiscovery#addObserverMethod(ObserverMethod)
* registering an instance} with the container.
*
* A portable extension may be notified of the existence of an
* enabled bean by observing the container lifecycle event type
* {@link jakarta.enterprise.inject.spi.ProcessBean} or one of its
* {@linkplain jakarta.enterprise.inject.spi.ProcessBean subtypes},
* or of the existence of an observer method of an enabled bean by
* observing the event type
* {@link jakarta.enterprise.inject.spi.ProcessObserverMethod}.
*
* Alternate metadata sources
*
* A portable extension may provide an alternative metadata
* source, such as configuration by XML.
*
* {@link jakarta.enterprise.inject.spi.Annotated}
* and its subtypes allow a portable extension to specify
* metadata that overrides the annotations that exist on a
* bean class. The portable extension is responsible for
* implementing the interfaces, thereby exposing the metadata
* to the container. The container must use the operations of
* Annotated and its subinterfaces to discover program
* element types and annotations, instead of directly calling the
* Java Reflection API.
*
* A portable extension provides its metadata to the
* container by observing the event
* {@link jakarta.enterprise.inject.spi.ProcessAnnotatedType} and
* {@linkplain jakarta.enterprise.inject.spi.ProcessAnnotatedType#setAnnotatedType(AnnotatedType)
* wrapping} the {@link jakarta.enterprise.inject.spi.AnnotatedType}.
*
* Producer and InjectionTarget
*
* The interfaces {@link jakarta.enterprise.inject.spi.Producer} and
* {@link jakarta.enterprise.inject.spi.InjectionTarget} abstract the
* basic lifecycle of (contextual or non-contextual) container managed
* objects, including instantiation and destruction, dependency injection
* and lifecycle callbacks.
*
* An instance of {@link jakarta.enterprise.inject.spi.InjectionTarget}
* may be product of
* {@linkplain jakarta.enterprise.inject.spi.BeanManager#getInjectionTargetFactory(AnnotatedType)}
* obtained from the {@link jakarta.enterprise.inject.spi.BeanManager},
* allowing a portable extension to request these container services for
* objects under the control of the portable extension.
*
* Furthermore, a portable extension may replace the implementation
* of {@link jakarta.enterprise.inject.spi.InjectionTarget} or
* {@link jakarta.enterprise.inject.spi.Producer} used by the container
* with its own implementation by observing the events
* {@link jakarta.enterprise.inject.spi.ProcessInjectionTarget} or
* {@link jakarta.enterprise.inject.spi.ProcessProducer}.
*
* @see jakarta.enterprise.inject
* @see jakarta.enterprise.context.spi
*/
package jakarta.enterprise.inject.spi;