Skip to content

Commit 693139b

Browse files
Ladicekmanovotn
Ladicek
authored and
manovotn
committed
comprehensive review and various Lite/Full split changes
1 parent fa71e2b commit 693139b

32 files changed

Lines changed: 754 additions & 545 deletions

‎spec/src/main/asciidoc/architecture.asciidoc‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ This specification defines a powerful set of complementary services that help to
77
* A sophisticated, typesafe _dependency injection_ mechanism, including the ability to select dependencies at either development or deployment time, without verbose configuration
88
* Support for Jakarta EE modularity and the Jakarta EE component architecture - the modular structure of a Jakarta EE application is taken into account when resolving dependencies between Jakarta EE components
99
* Integration with the Jakarta Unified Expression Language (EL), allowing any contextual object to be used directly within a Jakarta Server Faces or JSP page
10-
* The ability to _decorate_ injected objects
10+
* The ability to _decorate_ injected objects (only in {cdi_full} environment)
1111
* The ability to associate interceptors to objects via typesafe _interceptor bindings_
1212
* An _event notification_ model
13-
* A web _conversation context_ in addition to the three standard web contexts defined by the Jakarta Servlets specification
13+
* A web _conversation context_ in addition to the three standard web contexts defined by the Jakarta Servlets specification (only in {cdi_full} environment)
1414
* An SPI allowing _portable extensions_ to integrate cleanly with the container
1515

1616

@@ -27,7 +27,7 @@ In particular, Jakarta Enterprise Bean components may be used as Jakarta Server
2727
It's even possible to integrate with third-party frameworks.
2828
A portable extension may provide objects to be injected or obtain contextual instances using the dependency injection service. The framework may even raise and observe events using the event notification service.
2929

30-
An application that takes advantage of these services may be designed to execute in either the Jakarta EE environment or the Java SE environment.
30+
An application that takes advantage of these services may be designed to execute in the Jakarta EE environment, the Java SE environment, or in other environments that implement {cdi_lite}.
3131
If the application uses Jakarta EE services such as transaction management and persistence in the Java SE environment, the services are usually restricted to, at most, the subset defined for embedded usage by the Jakarta Enterprise Bean specification.
3232

3333
=== Contracts
@@ -41,13 +41,15 @@ This specification defines the responsibilities of:
4141
This runtime environment is called the _container_.
4242
For example, the container might be a Jakarta EE container or an embeddable Jakarta Enterprise Bean container.
4343

44-
<<concepts>>, <<implementation>>, <<inheritance>>, <<interceptors>>, <<decorator_bean>> and <<observer_methods>> define the programming model for Jakarta EE components that take advantage of the services defined by this specification, the responsibilities of the component developer, and the annotations used by the component developer to specify metadata.
44+
<<concepts>>, <<implementation>>, <<inheritance>>, <<interceptors>> and <<observer_methods>> define the programming model for application components that take advantage of the services defined by this specification, the responsibilities of the component developer, and the annotations used by the component developer to specify metadata.
45+
{cdi_full} adds <<specialization>> and <<decorator_bean>>.
4546

46-
<<injection_and_resolution>>, <<contexts>>, <<lifecycle>>, <<decorators>>, <<events>> and <<interceptor_resolution>> define the semantics and behavior of the services, the responsibilities of the container implementation and the APIs used by the application to interact directly with the container.
47+
<<injection_and_resolution>>, <<contexts>>, <<lifecycle>>, <<events>> and <<interceptor_resolution>> define the semantics and behavior of the services, the responsibilities of the container implementation and the APIs used by the application to interact directly with the container.
48+
{cdi_full} adds <<decorators>>.
4749

48-
<<packaging_deployment>> defines how Jakarta EE applications that use the services defined by this specification must be packaged into bean archives, and the responsibilities of the container implementation at application initialization time.
50+
<<packaging_deployment_lite>> and <<packaging_deployment>> defines how applications that use the services defined by this specification must be packaged into bean archives, and the responsibilities of the container implementation at application initialization time.
4951

50-
<<spi>>, <<contextual>> and <<context>> define an SPI that allows portable extensions to integrate with the container.
52+
<<spi>>, <<spi_lite>>, <<contextual>> and <<context>> define an SPI that allows portable extensions to integrate with the container.
5153

5254
=== Relationship to other specifications
5355

@@ -550,6 +552,11 @@ The invocation will proceed to the `DocumentEditor` class only if the authorizat
550552

551553
==== Decorator example
552554

555+
[NOTE]
556+
====
557+
Decorators are only available in {cdi_full}.
558+
====
559+
553560
_Decorators_ are similar to interceptors, but apply only to beans of a particular Java interface. Like interceptors, decorators may be easily enabled or disabled at deployment time. Unlike interceptors, decorators are aware of the semantics of the intercepted method.
554561

555562
For example, the `DataAccess` interface might be implemented by many beans:

‎spec/src/main/asciidoc/cdi-spec.asciidoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ include::core/interceptors.asciidoc[]
5353

5454
include::core/events.asciidoc[]
5555

56+
include::core/beanmanager_lite.asciidoc
57+
5658
include::core/spi_lite.asciidoc[]
5759

5860
include::core/packagingdeployment_lite.asciidoc[]
@@ -75,6 +77,10 @@ include::core/interceptors_full.asciidoc[]
7577

7678
include::core/decorators.asciidoc[]
7779

80+
include::core/interceptors_full.asciidoc[]
81+
82+
include::core/events_full.asciidoc[]
83+
7884
include::core/spi.asciidoc[]
7985

8086
include::core/packagingdeployment.asciidoc[]

‎spec/src/main/asciidoc/core/beanmanager_lite.asciidoc‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
[[programmatic_access]]
2+
3+
== Programmatic access to container
4+
5+
CDI 3.0 used to provide a single `BeanManager` object, which allows access to many useful operations.
6+
In CDI 4.0, this is split into `BeanManagerLite` and `BeanManager`.
7+
8+
`BeanManagerLite` provides access to a subset of `BeanManager` features which can be implemented in more restricted environments;
9+
It is available in {cdi_lite} environments.
10+
11+
`BeanManager` extends `BeanManagerLite` and provides the remaining features.
12+
It is available in {cdi_full} environments.
13+
14+
In {cdi_lite} environment, attempting to obtain a `BeanManager` or invoking methods on it results in non-portable behavior.
15+
16+
[[beanmanager]]
17+
18+
=== The `BeanManagerLite` object
19+
20+
The interface `jakarta.enterprise.inject.spi.BeanManagerLite` provides operations for obtaining contextual references for beans, along with many other operations of use to applications.
21+
22+
The container provides a built-in bean with bean type `BeanManagerLite`, scope `@Dependent` and qualifier `@Default`.
23+
Thus, any bean may obtain an instance of `BeanManagerLite` by injecting it:
24+
25+
[source, java]
26+
----
27+
@Inject BeanManagerLite manager;
28+
----
29+
30+
The operations of `BeanManagerLite` may be called at any time during the execution of the application.
31+
32+
[[provider]]
33+
34+
==== Obtaining a reference to the CDI container
35+
36+
Application objects sometimes interact directly with the container via programmatic API call.
37+
The abstract class `jakarta.enterprise.inject.spi.CDI` provides access to the `BeanManagerLite` as well providing lookup of bean instances.
38+
39+
[source, java]
40+
----
41+
public abstract class CDI<T> implements Instance<T> {
42+
public static CDI<Object> current() { ... }
43+
public static void setCDIProvider(CDIProvider provider);
44+
public abstract BeanManagerLite getBeanManagerLite();
45+
public abstract BeanManager getBeanManager();
46+
}
47+
----
48+
49+
An object may obtain a reference to the current container by calling `CDI.current()`.
50+
`CDI.getBeanManagerLite()`, as well as other methods on `CDI`, may be called after the application initialization is completed until the application shutdown starts.
51+
If methods on `CDI` are called at any other time, non-portable behavior results.
52+
53+
`CDI` implements `jakarta.enterprise.inject.Instance` and therefore might be used to perform programmatic lookup as defined in <<dynamic_lookup>>.
54+
If no qualifier is passed to `CDI.select()` method, the `@Default` qualifier is assumed.
55+
56+
When `CDI.current()` is called, `getCDI()` method is called on `jakarta.enterprise.inject.spi.CDIProvider`.
57+
58+
The `CDIProvider` to use may be set by the application or container using the `setCDIProvider()` method.
59+
If the `setCDIProvider()` has not been called, the service provider with highest priority of the service `jakarta.enterprise.inject.spi.CDIProvider` declared in META-INF/services is used.
60+
The order of more than one `CDIProvider` with the same priority is undefined.
61+
If no provider is available an `IllegalStateException` is thrown.
62+
63+
[source, java]
64+
----
65+
public interface CDIProvider extends Prioritized {
66+
CDI<Object> getCDI();
67+
default int getPriority();
68+
}
69+
----
70+
71+
* `getPriority()` method is inherited from <<prioritized, `Prioritized` interface>> and returns the priority for the `CDIProvider`.
72+
If this method is not implemented the default priority `0` is assumed.
73+
74+
75+
[[bm_obtain_contextual_reference]]
76+
77+
==== Obtaining a contextual reference for a bean
78+
79+
The method `BeanManagerLite.getReference()` returns a contextual reference for a given bean and bean type, as defined in <<contextual_reference>>.
80+
81+
[source, java]
82+
----
83+
public Object getReference(Bean<?> bean, Type beanType, CreationalContext<?> ctx);
84+
----
85+
86+
The first parameter is the `Bean` object representing the bean.
87+
The second parameter represents a bean type that must be implemented by any client proxy that is returned.
88+
The third parameter is an instance of `CreationalContext` that may be used to destroy any object with scope `@Dependent` that is created.
89+
90+
If the given type is not a bean type of the given bean, an `IllegalArgumentException` is thrown.
91+
92+
[[bm_obtain_injectable_reference]]
93+
94+
==== Obtaining an injectable reference
95+
96+
The method `BeanManagerLite.getInjectableReference()` returns an injectable reference for a given injection point, as defined in <<injectable_reference>>.
97+
98+
[source, java]
99+
----
100+
public Object getInjectableReference(InjectionPoint ij, CreationalContext<?> ctx);
101+
----
102+
103+
The first parameter represents the target injection point.
104+
The second parameter is an instance of `CreationalContext` that may be used to destroy any object with scope `@Dependent` that is created.
105+
106+
If typesafe resolution results in an unsatisfied dependency, the container must throw an `UnsatisfiedResolutionException`. If typesafe resolution results in an unresolvable ambiguous dependency, the container must throw an `AmbiguousResolutionException`.
107+
108+
Implementations of `Bean` usually maintain a reference to an instance of `BeanManagerLite`. When the `Bean` implementation performs dependency injection, it must obtain the contextual instances to inject by calling `BeanManagerLite.getInjectableReference()`, passing an instance of `InjectionPoint` that represents the injection point and the instance of `CreationalContext` that was passed to `Bean.create()`.
109+
110+
[[bm_obtain_creationalcontext]]
111+
112+
==== Obtaining a `CreationalContext`
113+
114+
An instance of `CreationalContext` for a certain instance of `Contextual` may be obtained by calling `BeanManagerLite.createCreationalContext()`.
115+
116+
[source, java]
117+
----
118+
public <T> CreationalContext<T> createCreationalContext(Contextual<T> contextual);
119+
----
120+
121+
An instance of `CreationalContext` for a non-contextual object may be obtained by passing a null value to `createCreationalContext()`.
122+
123+
[[bm_obtain_bean_by_type]]
124+
125+
==== Obtaining a `Bean` by type
126+
127+
The method `BeanManagerLite.getBeans()` returns the set of beans which have the given required type and qualifiers and are available for injection in the module or library containing the class into which the `BeanManagerLite` was injected, according to the rules for candidates of typesafe resolution defined in <<performing_typesafe_resolution>>.
128+
129+
[source, java]
130+
----
131+
public Set<Bean<?>> getBeans(Type beanType, Annotation... qualifiers);
132+
----
133+
134+
The first parameter is a required bean type. The remaining parameters are required qualifiers.
135+
136+
If no qualifiers are passed to `getBeans()`, the default qualifier `@Default` is assumed.
137+
138+
If the given type represents a type variable, an `IllegalArgumentException` is thrown.
139+
140+
If two instances of the same non repeating qualifier type are given, an `IllegalArgumentException` is thrown.
141+
142+
If an instance of an annotation that is not a qualifier type is given, an `IllegalArgumentException` is thrown.
143+
144+
[[bm_obtain_bean_by_name]]
145+
146+
==== Obtaining a `Bean` by name
147+
148+
The method `BeanManagerLite.getBeans()` which accepts a string returns the set of beans which have the given bean name and are available for injection in the module or library containing the class into which the `BeanManagerLite` was injected, according to the rules of name resolution defined in <<name_resolution>>.
149+
150+
[source, java]
151+
----
152+
public Set<Bean<?>> getBeans(String name);
153+
----
154+
155+
The parameter is a bean name.
156+
157+
[[bm_resolve_ambiguous_dep]]
158+
159+
==== Resolving an ambiguous dependency
160+
161+
The method `BeanManagerLite.resolve()` applies the ambiguous dependency resolution rules defined in <<unsatisfied_and_ambig_dependencies>> to a set of `Bean` s.
162+
163+
[source, java]
164+
----
165+
public <X> Bean<? extends X> resolve(Set<Bean<? extends X>> beans);
166+
----
167+
168+
If the ambiguous dependency resolution rules fail (as defined in <<unsatisfied_and_ambig_dependencies>>, the container must throw an `AmbiguousResolutionException`.
169+
170+
`BeanManagerLite.resolve()` must return null if:
171+
172+
* null is passed to `resolve()`, or
173+
* no beans are passed to `resolve()`.
174+
175+
[[bm_fire_event]]
176+
177+
==== Firing an event
178+
179+
The method `BeanManagerLite.getEvent()` returns an instance of `Event` with specified type `java.lang.Object` and specified qualifier `@Default`.
180+
181+
[source, java]
182+
----
183+
Event<Object> getEvent();
184+
----
185+
186+
The returned instance can be used like a standard `Event` as described in <<events>>.
187+
188+
[[bm_observer_method_resolution]]
189+
190+
==== Observer method resolution
191+
192+
The method `BeanManagerLite.resolveObserverMethods()` resolves observer methods for an event according to the rules of observer resolution defined in <<observer_resolution>>.
193+
194+
[source, java]
195+
----
196+
public <T> Set<ObserverMethod<? super T>> resolveObserverMethods(T event, Annotation... qualifiers);
197+
----
198+
199+
The first parameter of `resolveObserverMethods()` is the event object.
200+
The remaining parameters are event qualifiers.
201+
202+
If the runtime type of the event object contains a type variable, an `IllegalArgumentException` is thrown.
203+
204+
If two instances of the same non repeating qualifier type are given, an `IllegalArgumentException` is thrown.
205+
206+
If an instance of an annotation that is not a qualifier type is given, an `IllegalArgumentException` is thrown.
207+
208+
[[bm_interceptor_resolution]]
209+
210+
==== Interceptor resolution
211+
212+
The method `BeanManagerLite.resolveInterceptors()` returns the ordered list of interceptors for a set of interceptor bindings and a type of interception and which are enabled in the module or library containing the class into which the `BeanManagerLite` was injected, as defined in <<interceptor_resolution>>.
213+
214+
[source, java]
215+
----
216+
List<Interceptor<?>> resolveInterceptors(InterceptionType type,
217+
Annotation... interceptorBindings);
218+
----
219+
220+
If two instances of the same non repeating interceptor binding type are given, an `IllegalArgumentException` is thrown.
221+
222+
If no interceptor binding type instance is given, an `IllegalArgumentException` is thrown.
223+
224+
If an instance of an annotation that is not an interceptor binding type is given, an `IllegalArgumentException` is thrown.
225+
226+
[[bm_determining_annotation]]
227+
228+
==== Determining if an annotation is a qualifier type, scope type, stereotype or interceptor binding type
229+
230+
An application may test an annotation to determine if it is a qualifier type, scope type, stereotype or interceptor binding type, or determine if a scope type is a normal scope.
231+
232+
[source, java]
233+
----
234+
public boolean isScope(Class<? extends Annotation> annotationType);
235+
public boolean isNormalScope(Class<? extends Annotation> scopeType);
236+
237+
public boolean isQualifier(Class<? extends Annotation> annotationType);
238+
public boolean isInterceptorBinding(Class<? extends Annotation> annotationType);
239+
public boolean isStereotype(Class<? extends Annotation> annotationType);
240+
----
241+
242+
[[bm_obtain_active_context]]
243+
244+
==== Obtaining the active `Context` for a scope
245+
246+
The method `BeanManagerLite.getContext()` retrieves an active context object associated with the given scope, as defined in <<active_context>>.
247+
248+
[source, java]
249+
----
250+
public Context getContext(Class<? extends Annotation> scopeType);
251+
----
252+
253+
[[bm_obtain_instance]]
254+
255+
==== Obtain an `Instance`
256+
257+
The method `BeanManagerLite.createInstance()` returns an `Instance<Object>` to request bean instances programmatically as described in <<dynamic_lookup>>.
258+
259+
The returned `Instance` object can only access instances of beans that are available for injection in the module or library containing the class into which the `BeanManagerLite` was injected, according to the rules defined in <<typesafe_resolution>>.
260+
261+
[source, java]
262+
----
263+
Instance<Object> createInstance();
264+
----
265+
266+
Instances of dependent scoped beans obtained with this `Instance` object must be explicitly released by calling `Instance.destroy()` method.
267+
268+
If no qualifier is passed to `Instance.select()` method, the `@Default` qualifier is assumed.

0 commit comments

Comments
 (0)