Place the EL integration API to ELAwareBeanManager in a new supplemen…

…tal API artifact

The existing EL integration API in `BeanManager` is deprecated for removal.

api/src/main/java/jakarta/enterprise/inject/spi/BeanManager.java

@@ -227,9 +227,11 @@ public interface BeanManager extends BeanContainer {
 
     /**
      * Returns a {@link jakarta.el.ELResolver} that resolves beans by EL name.
-     * 
+     *
+     * @deprecated use {@code ELAwareBeanManager}, this method will be removed in CDI 5.0
      * @return the {@link jakarta.el.ELResolver}
      */
+    @Deprecated(since = "4.1", forRemoval = true)
     public ELResolver getELResolver();
 
     /**
@@ -239,10 +241,11 @@ public interface BeanManager extends BeanContainer {
      * {@link jakarta.el.ExpressionFactory}, the container handles destruction of objects with scope
      * {@link Dependent}.
      * 
-     * 
+     * @deprecated use {@code ELAwareBeanManager}, this method will be removed in CDI 5.0
      * @param expressionFactory the {@link jakarta.el.ExpressionFactory} to wrap
      * @return the wrapped {@link jakarta.el.ExpressionFactory}
      */
+    @Deprecated(since = "4.1", forRemoval = true)
     public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
 
     /**

el/pom.xml

@@ -0,0 +1,147 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>jakarta.enterprise</groupId>
+		<artifactId>jakarta.enterprise.cdi-parent</artifactId>
+		<version>4.1.0-SNAPSHOT</version>
+	</parent>
+
+	<artifactId>jakarta.enterprise.cdi-el-api</artifactId>
+	<packaging>jar</packaging>
+
+	<name>CDI EL integration API</name>
+	<description>API for integrating CDI with Unified EL</description>
+
+	<licenses>
+		<license>
+			<name>Apache License 2.0</name>
+			<url>https://repository.jboss.org/licenses/apache-2.0.txt</url>
+			<distribution>repo</distribution>
+		</license>
+	</licenses>
+
+	<properties>
+		<uel.api.version>5.0.0</uel.api.version>
+	</properties>
+
+	<dependencyManagement>
+		<dependencies>
+			<dependency>
+				<groupId>jakarta.enterprise</groupId>
+				<artifactId>jakarta.enterprise.cdi-api</artifactId>
+				<version>${project.version}</version>
+			</dependency>
+			<dependency>
+				<groupId>jakarta.el</groupId>
+				<artifactId>jakarta.el-api</artifactId>
+				<version>${uel.api.version}</version>
+			</dependency>
+		</dependencies>
+	</dependencyManagement>
+
+	<dependencies>
+		<dependency>
+			<groupId>jakarta.enterprise</groupId>
+			<artifactId>jakarta.enterprise.cdi-api</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>jakarta.el</groupId>
+			<artifactId>jakarta.el-api</artifactId>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<resources>
+			<resource>
+				<directory>${project.basedir}/..</directory>
+				<includes>
+					<include>LICENSE.txt</include>
+					<include>NOTICE.md</include>
+				</includes>
+				<targetPath>META-INF</targetPath>
+			</resource>
+			<resource>
+				<directory>src/main/resources</directory>
+			</resource>
+		</resources>
+
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<version>${maven-compiler-plugin.version}</version>
+				<configuration>
+					<compilerArgs>
+						<arg>-Xlint:all</arg>
+					</compilerArgs>
+				</configuration>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.felix</groupId>
+				<artifactId>maven-bundle-plugin</artifactId>
+				<version>${maven-bundle-plugin.version}</version>
+				<executions>
+					<execution>
+						<id>bundle-manifest</id>
+						<phase>process-classes</phase>
+						<goals>
+							<goal>manifest</goal>
+						</goals>
+					</execution>
+				</executions>
+				<configuration>
+					<instructions>
+						<Export-Package>
+							jakarta.enterprise.inject.spi.el;version=4.1,
+						</Export-Package>
+						<Import-Package>
+							jakarta.el;version=5.0
+						</Import-Package>
+					</instructions>
+				</configuration>
+			</plugin>
+			<!-- Add the OSGi Manifest to the main jar -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-jar-plugin</artifactId>
+				<version>${maven-jar-plugin.version}</version>
+				<configuration>
+					<archive>
+						<manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
+					</archive>
+				</configuration>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<version>${maven-javadoc-plugin.version}</version>
+				<configuration>
+					<docfilessubdirs>true</docfilessubdirs>
+					<description>Jakarta CDI EL integration API</description>
+					<doctitle>Jakarta CDI EL integration API</doctitle>
+					<windowtitle>Jakarta CDI EL integration API</windowtitle>
+					<header><![CDATA[<br>Jakarta CDI EL integration API ${project.version}]]>
+					</header>
+					<bottom><![CDATA[
+Comments to: <a href="mailto:[email protected]">[email protected]</a>.<br>
+Copyright &#169; 2018,2020 Eclipse Foundation.<br>
+Use is subject to <a href="{@docRoot}/doc-files/speclicense.html" target="_top">license terms</a>.]]>
+					</bottom>
+				</configuration>
+
+				<executions>
+					<execution>
+						<id>attach-javadocs</id>
+						<goals>
+							<goal>jar</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+
+
+</project>

el/src/main/java/jakarta/enterprise/inject/spi/el/ELAwareBeanManager.java

@@ -0,0 +1,34 @@
+package jakarta.enterprise.inject.spi.el;
+
+import jakarta.el.ELResolver;
+import jakarta.el.ExpressionFactory;
+import jakarta.enterprise.context.Dependent;
+import jakarta.enterprise.inject.spi.BeanManager;
+
+/**
+ * A {@link BeanManager} that allows integrators to obtain Unified EL objects
+ * that are integrated with the CDI container as described in the CDI specification.
+ *
+ * @since 4.1
+ */
+public interface ELAwareBeanManager extends BeanManager {
+    /**
+     * Returns a {@link jakarta.el.ELResolver} that resolves beans by EL name.
+     *
+     * @return the {@link jakarta.el.ELResolver}
+     */
+    public ELResolver getELResolver();
+
+    /**
+     * Returns a wrapper {@link jakarta.el.ExpressionFactory} that delegates {@link jakarta.el.MethodExpression} and
+     * {@link jakarta.el.ValueExpression} creation to the given {@link jakarta.el.ExpressionFactory}. When a Unified EL expression
+     * is evaluated using a {@link jakarta.el.MethodExpression} or {@link jakarta.el.ValueExpression} returned by the wrapper
+     * {@link jakarta.el.ExpressionFactory}, the container handles destruction of objects with scope
+     * {@link Dependent}.
+     *
+     * @param expressionFactory the {@link jakarta.el.ExpressionFactory} to wrap
+     * @return the wrapped {@link jakarta.el.ExpressionFactory}
+     */
+    public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
+
+}

el/src/main/java/module-info.java

@@ -0,0 +1,6 @@
+module jakarta.cdi.el {
+    exports jakarta.enterprise.inject.spi.el;
+
+    requires transitive jakarta.cdi;
+    requires transitive jakarta.el;
+}

el/src/main/javadoc/doc-files/speclicense.html

@@ -0,0 +1,72 @@
+<html>
+<head>
+  <title>Eclipse Foundation Specification License - v1.0</title>
+</head>
+<body>
+<h1>Eclipse Foundation Specification License - v1.0</h1>
+<p>By using and/or copying this document, or the Eclipse Foundation
+  document from which this statement is linked, you (the licensee) agree
+  that you have read, understood, and will comply with the following
+  terms and conditions:</p>
+
+<p>Permission to copy, and distribute the contents of this document, or
+  the Eclipse Foundation document from which this statement is linked, in
+  any medium for any purpose and without fee or royalty is hereby
+  granted, provided that you include the following on ALL copies of the
+  document, or portions thereof, that you use:</p>
+
+<ul>
+  <li> link or URL to the original Eclipse Foundation document.</li>
+  <li>All existing copyright notices, or if one does not exist, a notice
+    (hypertext is preferred, but a textual representation is permitted)
+    of the form: &quot;Copyright &copy; [$date-of-document]
+    &ldquo;Eclipse Foundation, Inc. &lt;&lt;url to this license&gt;&gt;
+    &quot;
+  </li>
+</ul>
+
+<p>Inclusion of the full text of this NOTICE must be provided. We
+  request that authorship attribution be provided in any software,
+  documents, or other items or products that you create pursuant to the
+  implementation of the contents of this document, or any portion
+  thereof.</p>
+
+<p>No right to create modifications or derivatives of Eclipse Foundation
+  documents is granted pursuant to this license, except anyone may
+  prepare and distribute derivative works and portions of this document
+  in software that implements the specification, in supporting materials
+  accompanying such software, and in documentation of such software,
+  PROVIDED that all such works include the notice below. HOWEVER, the
+  publication of derivative works of this document for use as a technical
+  specification is expressly prohibited.</p>
+
+<p>The notice is:</p>
+
+<p>&quot;Copyright &copy; 2018 Eclipse Foundation. This software or
+  document includes material copied from or derived from [title and URI
+  of the Eclipse Foundation specification document].&quot;</p>
+
+<h2>Disclaimers</h2>
+
+<p>THIS DOCUMENT IS PROVIDED &quot;AS IS,&quot; AND THE COPYRIGHT
+  HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR
+  WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+  NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE
+  SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS
+  WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR
+  OTHER RIGHTS.</p>
+
+<p>THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE
+  FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT
+  OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE
+  CONTENTS THEREOF.</p>
+
+<p>The name and trademarks of the copyright holders or the Eclipse
+  Foundation may NOT be used in advertising or publicity pertaining to
+  this document or its contents without specific, written prior
+  permission. Title to copyright in this document will at all times
+  remain with copyright holders.</p>
+
+</body>
+</html>

el/src/main/javadoc/overview.html

@@ -0,0 +1,11 @@
+<html>
+
+<body>
+
+<p>The CDI EL integration API enables CDI integration with Unified EL.
+The integration entrypoint is an <code>ELAwareBeanManager</code>, which allows
+obtaining a CDI-aware EL resolver and wrapping an EL expression factory into a CDI-aware one.</p>
+
+</body>
+
+</html>

pom.xml

@@ -33,6 +33,7 @@
 		<module>spec</module>
 		<module>lang-model</module>
 		<module>api</module>
+		<module>el</module>
 	</modules>
 	<build>
 		<defaultGoal>clean package</defaultGoal>

spec/src/main/asciidoc/core/spi_full.asciidoc

@@ -389,17 +389,6 @@ public int getQualifierHashCode(Annotation qualifier);
 public int getInterceptorBindingHashCode(Annotation interceptorBinding);
 ----
 
-[[bm_obtain_elresolver]]
-
-==== Obtaining the `ELResolver`
-
-The method `BeanManager.getELResolver()` returns the `jakarta.el.ELResolver` specified in <<el>>.
-
-[source, java]
-----
-public ELResolver getELResolver();
-----
-
 [[bm_obtain_annotatedtype]]
 
 ==== Obtaining an `AnnotatedType` for a class

spec/src/main/asciidoc/javaee/definition_ee.asciidoc

@@ -74,7 +74,7 @@ A bean with a name may be referred to by its name in Unified EL expressions.
 
 There is no relationship between the bean name of an EJB session bean and the EJB name of the bean.
 
-Bean names allow the direct use of beans in JSP or JSF pages, as defined in <<el>>.
+Bean names allow the direct use of beans in JSP or JSF pages.
 For example, a bean with the name `products` could be used like this:
 
 [source, xml]

spec/src/main/asciidoc/javaee/el.asciidoc

@@ -0,0 +1,46 @@
+[[el]]
+== Integration with Unified EL
+
+[[el_resolution]]
+=== Bean name resolution in EL expressions
+
+The container must provide a Unified EL `ELResolver` to the servlet engine and JSF implementation that resolves bean names using the rules of name resolution defined in <<name_resolution>> and resolving ambiguities according to <<ambig_names>>.
+
+* If a name used in an EL expression does not resolve to any bean, the `ELResolver` must return a null value.
+* Otherwise, if a name used in an EL expression resolves to exactly one bean, the `ELResolver` must return a contextual instance of the bean, as defined in <<contextual_instance>>.
+
+[[el_support]]
+=== Unified EL integration API
+
+Since CDI version 4.1, the Unified EL integration API, which is part of the `BeanManager` API, is deprecated.
+The relevant methods are placed in a new interface `jakarta.enterprise.inject.spi.el.ELAwareBeanManager`, which is present in a new supplemental CDI API artifact: `jakarta.enterprise:jakarta.enterprise.cdi-el-api`.
+
+==== Obtaining `ELAwareBeanManager`
+
+The `BeanManager` implementation in Jakarta EE must also implement `ELAwareBeanManager`.
+All rules that apply to the `BeanManager`, as specified in <<beanmanager>> and <<beanmanager_ee>>, also apply to `ELAwareBeanManager`.
+
+It follows that the container provides a built-in bean with bean type `ELAwareBeanManager`, scope `@Dependent` and qualifier `@Default`, which is a passivation capable dependency as defined in <<passivation_capable_dependency>>.
+It also follows that an `ELAwareBeanManager` may be obtained by using `CDI.current().getBeanManager()` and casting.
+
+The EL-related methods of `ELAwareBeanManager` may be called at any time during the execution of the application.
+
+==== Obtaining the `ELResolver`
+
+The method `ELAwareBeanManager.getELResolver()` returns the `jakarta.el.ELResolver` specified in <<el_resolution>>.
+This `ELResolver` is used to satisfy the rules defined in <<names_ee>>.
+
+[source, java]
+----
+public ELResolver getELResolver();
+----
+
+==== Wrapping a Unified EL `ExpressionFactory`
+
+The method `ELAwareBeanManager.wrapExpressionFactory()` returns a wrapper `jakarta.el.ExpressionFactory` that delegates `MethodExpression` and `ValueExpression` creation to the given `ExpressionFactory`.
+When a Unified EL expression is evaluated using a `MethodExpression` or `ValueExpression` returned by the wrapper `ExpressionFactory`, the rules defined in <<dependent_scope_el>> are enforced by the container.
+
+[source, java]
+----
+public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
+----

spec/src/main/asciidoc/javaee/javaeeintegration.asciidoc

@@ -27,3 +27,5 @@ include::events_ee.asciidoc[]
 include::spi_ee.asciidoc[]
 
 include::packagingdeployment_ee.asciidoc[]
+
+include::el.asciidoc[]