API changes for allowing @Priority on stereotypes

api/src/main/java/jakarta/enterprise/inject/Stereotype.java

@@ -85,7 +85,8 @@
  * 
  * <ul>
  * <li>all beans with the stereotype have defaulted bean EL names, or that</li>
- * <li>all beans with the stereotype are alternatives.</li>
+ * <li>all beans with the stereotype are alternatives, or that</li>
+ * <li>all beans with the stereotype have predefined {@code @Priority}.</li>
  * </ul>
  * 
  * <p>
@@ -120,6 +121,21 @@
  * </pre>
  * 
  * <p>
+ * A stereotype may declare a {@link jakarta.annotation.Priority &#064;Priority} annotation, which specifies that
+ * every bean with the stereotype has given priority. This enables and orders alternatives, interceptors, and decorators.
+ * </p>
+ *
+ * <pre>
+ * &#064;Alternative
+ * &#064;Priority(1)
+ * &#064;Stereotype
+ * &#064;Target(TYPE)
+ * &#064;Retention(RUNTIME)
+ * public @interface Mock {
+ * }
+ * </pre>
+ *
+ * <p>
  * A stereotype may declare other stereotypes. Stereotype declarations are transitive. A stereotype declared by a second
  * stereotype is inherited by all beans and other stereotypes that declare the second stereotype.
  * </p>

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BeanInfo.java

@@ -113,14 +113,13 @@ public interface BeanInfo {
     boolean isAlternative();
 
     /**
-     * Returns the {@linkplain jakarta.annotation.Priority priority} of this alternative bean.
-     * If this bean is not an alternative, the return value is undefined.
+     * Returns the {@linkplain jakarta.annotation.Priority priority} declared on this bean, or {@code null}
+     * if this bean does not declare a priority. Declaring a priority on an alternative bean makes it an enabled
+     * alternative. Similarly, declaring a priority on an interceptor makes it an enabled interceptor.
      *
-     * @return the priority of this alternative bean
-     * @see #isAlternative()
+     * @return the priority of this bean, or {@code null} if this bean does not declare a priority
      */
-    // TODO maybe specify that if this bean is not an alternative, this returns 0?
-    int priority();
+    Integer priority();
 
     /**
      * Returns the bean name of this bean. A bean name is usually defined

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/StereotypeInfo.java

@@ -32,18 +32,27 @@ public interface StereotypeInfo {
      * Returns whether this stereotype is meta-annotated {@link jakarta.enterprise.inject.Alternative @Alternative}.
      * This means that all beans with this stereotype are alternatives.
      *
-     * @return whether this stereotype is meta-annotated {@link jakarta.enterprise.inject.Alternative @Alternative}.
+     * @return whether this stereotype is meta-annotated {@link jakarta.enterprise.inject.Alternative @Alternative}
      */
     boolean isAlternative();
 
-    // TODO https://github.com/eclipse-ee4j/cdi/issues/495
-    //int priority();
+    /**
+     * Returns the priority value this stereotype declares using the {@link jakarta.annotation.Priority @Priority}
+     * meta-annotation. All alternatives and interceptors with this stereotype will be enabled for the application
+     * and ordered using this priority value (unless they declare priority explicitly).
+     * <p>
+     * Returns {@code null} if this stereotype is not meta-annotated {@code @Priority}.
+     *
+     * @return the {@link jakarta.annotation.Priority @Priority} value declared by this stereotype, or {@code null}
+     * if this stereotype is not meta-annotated {@code @Priority}
+     */
+    Integer priority();
 
     /**
      * Returns whether this stereotype is meta-annotated {@link jakarta.inject.Named @Named}.
      * This means that all beans with this stereotype have default bean names.
      *
-     * @return whether this stereotype is meta-annotated {@link jakarta.inject.Named @Named}.
+     * @return whether this stereotype is meta-annotated {@link jakarta.inject.Named @Named}
      */
     boolean isNamed();
 }