Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Formatting rules #731

Merged
merged 6 commits into from
Dec 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci-actions.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,4 @@ spec/en/master-filtered.xml
*.iws
.idea
*.swp
.cache
12 changes: 7 additions & 5 deletions api/src/main/java/jakarta/decorator/Decorator.java
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -29,19 +29,21 @@
* <p>
* Specifies that a class is a decorator. May be applied to a managed bean class.
* </p>
*
*
* <pre>
* &#064;Decorator
* &#064;Decorator
* class TimestampLogger implements Logger { ... }
* </pre>
*
*
* <p>
* 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.
* </p>
*
* <p>CDI Lite implementations are not required to provide support for decorators.</p>
* <p>
* CDI Lite implementations are not required to provide support for decorators.
* </p>
*
* @see Delegate &#064;Delegate identifies the delegate injection point of a decorator.
*
Expand Down
48 changes: 25 additions & 23 deletions api/src/main/java/jakarta/decorator/Delegate.java
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -29,56 +29,58 @@
* 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.
* </p>
*
*
* <pre>
* &#064;Decorator
* class TimestampLogger implements Logger {
* &#064;Inject &#064;Delegate &#064;Any Logger logger;
* ...
* &#064;Decorator
* class TimestampLogger implements Logger {
* &#064;Inject &#064;Delegate &#064;Any Logger logger;
* ...
* }
* </pre>
*
*
* <pre>
* &#064;Decorator
* class TimestampLogger implements Logger {
* &#064;Decorator
* class TimestampLogger implements Logger {
* private Logger logger;
*
*
* &#064;Inject
* public TimestampLogger(&#064;Delegate &#064;Debug Logger logger) {
* this.logger=logger;
* }
* ...
* public TimestampLogger(&#064;Delegate &#064;Debug Logger logger) {
* this.logger=logger;
* }
* ...
* }
* </pre>
*
*
* <p>
* 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.
* </p>
*
*
* <p>
* 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}.
* </p>
*
*
* <pre>
* &#064;Decorator
* class TimestampLogger implements Logger {
* &#064;Inject &#064;Delegate &#064;Any Logger logger;
*
* &#064;Decorator
* class TimestampLogger implements Logger {
* &#064;Inject &#064;Delegate &#064;Any Logger logger;
*
* void log(String message) {
* logger.log( timestamp() + ": " + message );
* }
* ...
* }
* </pre>
*
* <p>CDI Lite implementations are not required to provide support for decorators.</p>
* <p>
* CDI Lite implementations are not required to provide support for decorators.
* </p>
*
* @see Decorator &#064;Decorator specifies that a class is a decorator.
*
*
* @author Gavin King
* @author Pete Muir
*/
Expand Down
149 changes: 87 additions & 62 deletions api/src/main/java/jakarta/decorator/package-info.java
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
/**
* <p>Annotations relating to decorators.</p>
*
* <p>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.</p>
*
* <p>A decorator is a managed bean annotated {@link
* jakarta.decorator.Decorator &#064;Decorator}.</p>
*
* <p>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.</p>
*
* <p>
* Annotations relating to decorators.
* </p>
*
* <p>
* 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.
* </p>
*
* <p>
* A decorator is a managed bean annotated {@link
* jakarta.decorator.Decorator &#064;Decorator}.
* </p>
*
* <p>
* 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.
* </p>
*
* <h2>Decorated types</h2>
*
* <p>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.</p>
*
* <p>A decorator intercepts every method:</p>
*
* <p>
* 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.
* </p>
*
* <p>
* A decorator intercepts every method:
* </p>
* <ul>
* <li>declared by a decorated type of the decorator</li>
* <li>that is implemented by the bean class of the decorator.</li>
* </ul>
*
* <p>A decorator may be an abstract class, and is not required to
* implement every method of every decorated type.</p>
*
*
* <p>
* A decorator may be an abstract class, and is not required to
* implement every method of every decorated type.
* </p>
*
* <h2>Delegate injection points</h2>
*
* <p>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 &#064;Delegate}.</p>
*
* <p>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.</p>
*
*
* <p>
* 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 &#064;Delegate}.
* </p>
*
* <p>
* 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.
* </p>
*
* <h2>Enabled decorators</h2>
*
* <p>By default, a bean archive has no enabled decorators. A
* decorator must be explicitly enabled by listing its bean class
*
* <p>
* By default, a bean archive has no enabled decorators. A
* decorator must be explicitly enabled by listing its bean class
* under the <code>&lt;decorators&gt;</code> element of the
* <code>beans.xml</code> 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.</p>
*
* <p>A decorator is bound to a bean if:</p>
*
* decorator declarations determines the decorator ordering.
* Decorators which occur earlier in the list are called first.
* </p>
*
* <p>
* A decorator is bound to a bean if:
* </p>
*
* <ul>
* <li>The bean is {@linkplain jakarta.enterprise.inject eligible for injection}
* <li>The bean is {@linkplain jakarta.enterprise.inject eligible for injection}
* to the delegate injection point of the decorator.</li>
* <li>The decorator is enabled in the bean archive of the bean.</li>
* </ul>
*
* <p>If a managed bean class is declared final, it may not have
* decorators. If a managed bean has a non-static, non-private,
*
* <p>
* 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.</p>
*
* <p>A decorator instance is a
* {@linkplain jakarta.enterprise.context.Dependent dependent object}
* of the object it decorates.</p>
*
* that method.
* </p>
*
* <p>
* A decorator instance is a
* {@linkplain jakarta.enterprise.context.Dependent dependent object}
* of the object it decorates.
* </p>
*
* @see jakarta.enterprise.inject
*
*
* @see jakarta.decorator.Decorator
* @see jakarta.decorator.Delegate
*
*
*/
package jakarta.decorator;

26 changes: 13 additions & 13 deletions api/src/main/java/jakarta/enterprise/context/ApplicationScoped.java
Original file line number Diff line number Diff line change
Expand Up @@ -34,17 +34,17 @@
* </p>
* <p>
* While <code>ApplicationScoped</code> 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.
* </p>
*
* <p>
* The application scope is active:
* </p>
*
* <ul>
* <li>during the <code>service()</code> method of any servlet in the web application, during the <code>doFilter()</code> method of any
* servlet filter and when the container calls any <code>ServletContextListener</code>, <code>HttpSessionListener</code>,
* <li>during the <code>service()</code> method of any servlet in the web application, during the <code>doFilter()</code> method
* of any servlet filter and when the container calls any <code>ServletContextListener</code>, <code>HttpSessionListener</code>,
* <code>AsyncListener</code> or <code>ServletRequestListener</code>,</li>
* <li>during any Java EE web service invocation,</li>
* <li>during any remote method invocation of any EJB, during any asynchronous method invocation of any EJB, during any call to
Expand All @@ -64,15 +64,15 @@
* </p>
*
* <p>
* An event with qualifier <code>@Initialized(ApplicationScoped.class)</code> is fired when the application context is initialized
* and an event with qualifier <code>@Destroyed(ApplicationScoped.class)</code> when the application context is destroyed.
* The event payload is:
* </p>
*
* <ul>
* <li>the <code>ServletContext</code> if the application is a web application deployed to a Servlet container, or</li>
* <li>any <code>java.lang.Object</code> for other types of application.</li>
* </ul>
* An event with qualifier <code>@Initialized(ApplicationScoped.class)</code> is fired when the application context is
* initialized and an event with qualifier <code>@Destroyed(ApplicationScoped.class)</code> when the application context is
* destroyed. The event payload is:
* </p>
*
* <ul>
* <li>the <code>ServletContext</code> if the application is a web application deployed to a Servlet container, or</li>
* <li>any <code>java.lang.Object</code> for other types of application.</li>
* </ul>
*
* @author Gavin King
* @author Pete Muir
Expand Down
Loading