diff --git a/.github/workflows/ci-actions.yml b/.github/workflows/ci-actions.yml index ddc6db3bb..61c79891f 100644 --- a/.github/workflows/ci-actions.yml +++ b/.github/workflows/ci-actions.yml @@ -25,11 +25,11 @@ jobs: - if: ${{ matrix.java != '11' }} name: "Maven install > 11" run: | - mvn -Pstaging install -DskipTests=true -B -V + mvn -Pstaging install -DskipTests=true -Dno-format -B -V - if: ${{ matrix.java == '11' }} name: "Maven install 11" run: | - mvn -Pstaging -pl '!el' install -DskipTests=true -B -V + mvn -Pstaging -pl '!el' install -DskipTests=true -Dno-format -B -V - if: ${{ matrix.java != '11' }} name: "Maven test > 11" run: | diff --git a/.gitignore b/.gitignore index dccf579c8..58515ad74 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ spec/en/master-filtered.xml *.iws .idea *.swp +.cache diff --git a/api/src/main/java/jakarta/decorator/Decorator.java b/api/src/main/java/jakarta/decorator/Decorator.java index 3b3578ac5..e7497f711 100644 --- a/api/src/main/java/jakarta/decorator/Decorator.java +++ b/api/src/main/java/jakarta/decorator/Decorator.java @@ -8,7 +8,7 @@ * 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, + * 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. @@ -29,19 +29,21 @@ *

* Specifies that a class is a decorator. May be applied to a managed bean class. *

- * + * * 
- * @Decorator 
+ * @Decorator
  * class TimestampLogger implements Logger { ... }
  *
- * + * *

* Decorators of a session bean must comply with the bean provider programming restrictions defined by the EJB specification. * Decorators of a stateful session bean must comply with the rules for instance passivation and conversational state defined by * the EJB specification. *

* - *

CDI Lite implementations are not required to provide support for decorators.

+ *

+ * CDI Lite implementations are not required to provide support for decorators. + *

* * @see Delegate @Delegate identifies the delegate injection point of a decorator. * diff --git a/api/src/main/java/jakarta/decorator/Delegate.java b/api/src/main/java/jakarta/decorator/Delegate.java index 23e331a77..4e7573897 100644 --- a/api/src/main/java/jakarta/decorator/Delegate.java +++ b/api/src/main/java/jakarta/decorator/Delegate.java @@ -8,7 +8,7 @@ * 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, + * 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. @@ -29,45 +29,45 @@ * Identifies the delegate injection point of a decorator. May be applied to a field, bean constructor parameter or initializer * method parameter of a decorator bean class. *

- * + * * 
- * @Decorator 
- * class TimestampLogger implements Logger { 
- *    @Inject @Delegate @Any Logger logger; 
- *    ... 
+ * @Decorator
+ * class TimestampLogger implements Logger {
+ *    @Inject @Delegate @Any Logger logger;
+ *    ...
  * }
  *
- * + * * 
- * @Decorator 
- * class TimestampLogger implements Logger { 
+ * @Decorator
+ * class TimestampLogger implements Logger {
  *    private Logger logger;
- *    
+ *
  *    @Inject
- *    public TimestampLogger(@Delegate @Debug Logger logger) { 
- *       this.logger=logger; 
- *    } 
- *    ... 
+ *    public TimestampLogger(@Delegate @Debug Logger logger) {
+ *       this.logger=logger;
+ *    }
+ *    ...
  * }
  *
- * + * *

* A decorator must have exactly one delegate injection point. The delegate injection point must be an injected field, * initializer method parameter or bean constructor method parameter. *

- * + * *

* The container injects a delegate object to the delegate injection point. The delegate object implements the delegate type and * delegates method invocations along the decorator stack. When the container calls a decorator during business method * interception, the decorator may invoke any method of the delegate object. If a decorator invokes the delegate object at any * other time, the invoked method throws an {@link java.lang.IllegalStateException}. *

- * + * * 
- * @Decorator 
- * class TimestampLogger implements Logger { 
- *    @Inject @Delegate @Any Logger logger; 
- *    
+ * @Decorator
+ * class TimestampLogger implements Logger {
+ *    @Inject @Delegate @Any Logger logger;
+ *
  *    void log(String message) {
  *       logger.log( timestamp() + ": " + message );
  *    }
@@ -75,10 +75,12 @@
  * }
  *
* - *

CDI Lite implementations are not required to provide support for decorators.

+ *

+ * CDI Lite implementations are not required to provide support for decorators. + *

* * @see Decorator @Decorator specifies that a class is a decorator. - * + * * @author Gavin King * @author Pete Muir */ diff --git a/api/src/main/java/jakarta/decorator/package-info.java b/api/src/main/java/jakarta/decorator/package-info.java index 4610ed955..14bf3a78a 100644 --- a/api/src/main/java/jakarta/decorator/package-info.java +++ b/api/src/main/java/jakarta/decorator/package-info.java @@ -8,89 +8,114 @@ * 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, + * 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.

- * + *

+ * 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:

+ * + *

+ * 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: + *

* - * - *

A decorator may be an abstract class, and is not required to - * implement every method of every decorated type.

- * + * + *

+ * 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.

- * + * + *

+ * 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 + * + *

+ * 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:

- * + * decorator declarations determines the decorator ordering. + * Decorators which occur earlier in the list are called first. + *

+ * + *

+ * A decorator is bound to a bean if: + *

+ * * - * - *

If a managed bean class is declared final, it may not have - * decorators. If a managed bean has a non-static, non-private, + * + *

+ * 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.

- * + * 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; - diff --git a/api/src/main/java/jakarta/enterprise/context/ApplicationScoped.java b/api/src/main/java/jakarta/enterprise/context/ApplicationScoped.java index a9ede12e3..6ab372aed 100644 --- a/api/src/main/java/jakarta/enterprise/context/ApplicationScoped.java +++ b/api/src/main/java/jakarta/enterprise/context/ApplicationScoped.java @@ -34,8 +34,8 @@ *

*

* While ApplicationScoped must be associated with the built-in application context required by the specification, - * third-party extensions are - * allowed to also associate it with their own context. Behavior described below is only related to the built-in application context. + * third-party extensions are allowed to also associate it with their own context. Behavior described below is only related to + * the built-in application context. *

* *

@@ -43,8 +43,8 @@ *

* * *

- * An event with qualifier @Initialized(ConversationScoped.class) is fired when the conversation context is initialized - * and an event with qualifier @Destroyed(ConversationScoped.class) is fired when the conversation is destroyed. - * The event payload is: + * An event with qualifier @Initialized(ConversationScoped.class) is fired when the conversation context is + * initialized and an event with qualifier @Destroyed(ConversationScoped.class) is fired when the conversation is + * destroyed. The event payload is: *

* @@ -63,10 +64,10 @@ *
  • Any Servlet request has exactly one associated conversation.
    • *
  • The container provides a filter with the name "CDI Conversation Filter", which may be mapped in web.xml, * allowing the user alter when the conversation is associated with the servlet request. If this filter is not mapped in any - * web.xml in the application, the conversation associated with a Servlet request is determined at the beginning of the - * request before calling any service() method of any servlet in the web application, calling the doFilter() - * method of any servlet filter in the web application and before the container calls any ServletRequestListener or - * AsyncListener in the web application.
    • + * web.xml in the application, the conversation associated with a Servlet request is determined at the beginning of + * the request before calling any service() method of any servlet in the web application, calling the + * doFilter() method of any servlet filter in the web application and before the container calls any + * ServletRequestListener or AsyncListener in the web application. * * * @@ -106,14 +107,14 @@ *
  • The long-running conversation context associated with a request that renders a JSF view is automatically propagated to * any faces request (JSF form submission) that originates from that rendered page.
    • *
  • The long-running conversation context associated with a request that results in a JSF redirect (a redirect resulting from - * a navigation rule or JSF NavigationHandler) is automatically propagated to the resulting non-faces request, and to any other - * subsequent request to the same URL. This is accomplished via use of a request parameter named cid containing the - * unique identifier of the conversation.
    • + * a navigation rule or JSF NavigationHandler) is automatically propagated to the resulting non-faces request, and + * to any other subsequent request to the same URL. This is accomplished via use of a request parameter named cid + * containing the unique identifier of the conversation. * * *

    - * When no conversation is propagated to a Servlet request, or if a request parameter named conversationPropagation has - * the value none the request is associated with a new transient conversation. + * When no conversation is propagated to a Servlet request, or if a request parameter named conversationPropagation + * has the value none the request is associated with a new transient conversation. * All long-running conversations are scoped to a particular HTTP servlet session and may not cross session boundaries. * In the following cases, a propagated long-running conversation cannot be restored and re-associated with the request: *

    @@ -125,7 +126,9 @@ * Servlet request, in order to conserve resources. * * - *

    CDI Lite implementations are not required to provide support for conversations.

    + *

    + * CDI Lite implementations are not required to provide support for conversations. + *

    * * @see Conversation * @see NonexistentConversationException diff --git a/api/src/main/java/jakarta/enterprise/context/Dependent.java b/api/src/main/java/jakarta/enterprise/context/Dependent.java index 02583b17e..762b30d54 100644 --- a/api/src/main/java/jakarta/enterprise/context/Dependent.java +++ b/api/src/main/java/jakarta/enterprise/context/Dependent.java @@ -26,14 +26,13 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +import jakarta.enterprise.context.spi.Context; import jakarta.enterprise.context.spi.Contextual; import jakarta.enterprise.context.spi.CreationalContext; +import jakarta.enterprise.inject.Instance; import jakarta.enterprise.util.AnnotationLiteral; import jakarta.inject.Scope; -import jakarta.enterprise.context.spi.Context; -import jakarta.enterprise.inject.Instance; - /** *

    * Specifies that a bean belongs to the dependent pseudo-scope. @@ -59,13 +58,13 @@ * * *

    - * Every invocation of the {@link Context#get(Contextual, CreationalContext)} operation of the - * context object for the @Dependent scope returns a new instance of the given bean. + * Every invocation of the {@link Context#get(Contextual, CreationalContext)} operation of the context object for the + * @Dependent scope returns a new instance of the given bean. *

    * *

    - * Every invocation of the {@link Context#get(Contextual)} operation of the context object for the - * @Dependent scope returns a null value. + * Every invocation of the {@link Context#get(Contextual)} operation of the context object for the @Dependent scope + * returns a null value. *

    * *

    @@ -73,18 +72,18 @@ *

    * *

    - * Many instances of beans with scope @Dependent belong to some other bean or Java EE component class instance and are - * called dependent objects. + * Many instances of beans with scope @Dependent belong to some other bean or Java EE component class instance and + * are called dependent objects. *

    * * * *

    diff --git a/api/src/main/java/jakarta/enterprise/context/Destroyed.java b/api/src/main/java/jakarta/enterprise/context/Destroyed.java index 760c878c8..8d733786d 100644 --- a/api/src/main/java/jakarta/enterprise/context/Destroyed.java +++ b/api/src/main/java/jakarta/enterprise/context/Destroyed.java @@ -46,6 +46,7 @@ /** * The scope for which to observe destruction + * * @return the scope type class */ Class value(); diff --git a/api/src/main/java/jakarta/enterprise/context/Initialized.java b/api/src/main/java/jakarta/enterprise/context/Initialized.java index 49b2035e7..9e8549c5f 100644 --- a/api/src/main/java/jakarta/enterprise/context/Initialized.java +++ b/api/src/main/java/jakarta/enterprise/context/Initialized.java @@ -46,6 +46,7 @@ /** * The scope for which to observe initialization + * * @return the scope type class */ Class value(); @@ -56,13 +57,13 @@ * @author Martin Kouba */ public final static class Literal extends AnnotationLiteral implements Initialized { - - public static final Literal REQUEST = of(RequestScoped.class); - + + public static final Literal REQUEST = of(RequestScoped.class); + public static final Literal CONVERSATION = of(ConversationScoped.class); - + public static final Literal SESSION = of(SessionScoped.class); - + public static final Literal APPLICATION = of(ApplicationScoped.class); private static final long serialVersionUID = 1L; diff --git a/api/src/main/java/jakarta/enterprise/context/NonexistentConversationException.java b/api/src/main/java/jakarta/enterprise/context/NonexistentConversationException.java index 9c4b7c140..7a8bf2d8a 100644 --- a/api/src/main/java/jakarta/enterprise/context/NonexistentConversationException.java +++ b/api/src/main/java/jakarta/enterprise/context/NonexistentConversationException.java @@ -8,7 +8,7 @@ * 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, + * 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. @@ -20,16 +20,18 @@ *

    * Indicates that the conversation context could not be restored. *

    - * + * *

    * If the propagated conversation cannot be restored, the container must associate the request with a new transient conversation * and throw an exception of type NonexistentConversationException. *

    * - *

    CDI Lite implementations are not required to provide support for conversations.

    - * + *

    + * CDI Lite implementations are not required to provide support for conversations. + *

    + * * @see ConversationScoped - * + * * @author Pete Muir * @author Gavin King */ diff --git a/api/src/main/java/jakarta/enterprise/context/NormalScope.java b/api/src/main/java/jakarta/enterprise/context/NormalScope.java index fae6ceb68..484d04daa 100644 --- a/api/src/main/java/jakarta/enterprise/context/NormalScope.java +++ b/api/src/main/java/jakarta/enterprise/context/NormalScope.java @@ -8,7 +8,7 @@ * 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, + * 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. @@ -27,10 +27,10 @@ *

    * Specifies that an annotation type is a normal scope type. *

    - * + * * @author Gavin King * @author Pete Muir - * + * * @see jakarta.inject.Scope @Scope is used to declare pseudo-scopes. */ @Target(ANNOTATION_TYPE) @@ -42,12 +42,12 @@ *

    * Determines whether the normal scope type is a passivating scope. *

    - * + * *

    * A bean is called passivation capable if the container is able to temporarily transfer the state of any idle instance to * secondary storage. A passivating scope requires that beans with the scope are passivation capable. *

    - * + * * @return true if the scope type is a passivating scope type */ boolean passivating() default false; diff --git a/api/src/main/java/jakarta/enterprise/context/RequestScoped.java b/api/src/main/java/jakarta/enterprise/context/RequestScoped.java index c6af80f85..da2b0369d 100644 --- a/api/src/main/java/jakarta/enterprise/context/RequestScoped.java +++ b/api/src/main/java/jakarta/enterprise/context/RequestScoped.java @@ -34,8 +34,8 @@ *

    *

    * While RequestScoped must be associated with the built-in request context required by the specification, - * third-party extensions are - * allowed to also associate it with their own context. Behavior described below is only related to the built-in request context. + * third-party extensions are allowed to also associate it with their own context. Behavior described below is only related to + * the built-in request context. *

    * *

    @@ -43,8 +43,9 @@ *

    * * * *

    - * An event with qualifier @Initialized(RequestScoped.class) is fired when the request context is initialized and an - * event - * with qualifier @Destroyed(RequestScoped.class) when the request context is destroyed. The event payload is: + * An event with qualifier @Initialized(RequestScoped.class) is fired when the request context is initialized and + * an event with qualifier @Destroyed(RequestScoped.class) when the request context is destroyed. The event payload + * is: *

    * *