Skip to content

Commit

Permalink
Manually reflow paragraphs with bad linebreaks
Browse files Browse the repository at this point in the history 
The autoformat settings will not join lines together which has resulted
in some cases where the line lengths are very uneven because the
formatter has needed to break a line which was slightly too long.

Reflow these paragraphs manually.

Signed-off-by: Andrew Rouse <[email protected]>
  • Loading branch information
@Azquelt @manovotn
Azquelt authored and manovotn committed Dec 13, 2023
1 parent f415eaa commit 04bee17
Show file tree
Hide file tree
Showing 25 changed files with 106 additions and 166 deletions.
13 changes: 5 additions & 8 deletions api/src/main/java/jakarta/enterprise/context/ApplicationScoped.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,8 @@
* </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>
Expand All @@ -45,8 +44,7 @@
*
* <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>,
* 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 @@ -67,9 +65,8 @@
*
* <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:
* initialized and an event with qualifier <code>@Destroyed(ApplicationScoped.class)</code> when the application context is
* destroyed. The event payload is:
* </p>
*
* <ul>
Expand Down
27 changes: 10 additions & 17 deletions api/src/main/java/jakarta/enterprise/context/ConversationScoped.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,8 @@
* </p>
* <p>
* While <code>ConversationScoped</code> must be associated with the built-in conversation 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 conversation
* context.
* specification, third-party extensions are allowed to also associate it with their own context. Behavior described below is
* only related to the built-in conversation context.
* </p>
* <p>
* The conversation scope is active:
Expand All @@ -47,9 +45,8 @@
* </ul>
* <p>
* An event with qualifier <code>@Initialized(ConversationScoped.class)</code> is fired when the conversation context is
* initialized
* and an event with qualifier <code>@Destroyed(ConversationScoped.class)</code> is fired when the conversation is destroyed.
* The event payload is:
* initialized and an event with qualifier <code>@Destroyed(ConversationScoped.class)</code> is fired when the conversation is
* destroyed. The event payload is:
* </p>
* <ul>
* <li>the conversation id if the conversation context is destroyed and is not associated with a current Servlet request,
Expand All @@ -68,11 +65,9 @@
* <li>The container provides a filter with the name "CDI Conversation Filter", which may be mapped in <code>web.xml</code>,
* allowing the user alter when the conversation is associated with the servlet request. If this filter is not mapped in any
* <code>web.xml</code> in the application, the conversation associated with a Servlet request is determined at the beginning of
* the
* request before calling any <code>service()</code> method of any servlet in the web application, calling the
* <code>doFilter()</code>
* method of any servlet filter in the web application and before the container calls any <code>ServletRequestListener</code> or
* <code>AsyncListener</code> in the web application.</li>
* the request before calling any <code>service()</code> method of any servlet in the web application, calling the
* <code>doFilter()</code> method of any servlet filter in the web application and before the container calls any
* <code>ServletRequestListener</code> or <code>AsyncListener</code> in the web application.</li>
* </ul>
*
*
Expand Down Expand Up @@ -113,15 +108,13 @@
* any faces request (JSF form submission) that originates from that rendered page.</li>
* <li>The long-running conversation context associated with a request that results in a JSF redirect (a redirect resulting from
* a navigation rule or JSF <code>NavigationHandler</code>) 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 <code>cid</code> containing the
* unique identifier of the conversation.</li>
* to any other subsequent request to the same URL. This is accomplished via use of a request parameter named <code>cid</code>
* containing the unique identifier of the conversation.</li>
* </ul>
*
* <p>
* When no conversation is propagated to a Servlet request, or if a request parameter named <code>conversationPropagation</code>
* has
* the value <code>none</code> the request is associated with a new transient conversation.
* has the value <code>none</code> 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:
* </p>
Expand Down
18 changes: 8 additions & 10 deletions api/src/main/java/jakarta/enterprise/context/Dependent.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,13 +58,13 @@
* </ul>
*
* <p>
* Every invocation of the {@link Context#get(Contextual, CreationalContext)} operation of the
* context object for the <code>@Dependent</code> 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
* <code>@Dependent</code> scope returns a new instance of the given bean.
* </p>
*
* <p>
* Every invocation of the {@link Context#get(Contextual)} operation of the context object for the
* <code>@Dependent</code> scope returns a null value.
* Every invocation of the {@link Context#get(Contextual)} operation of the context object for the <code>@Dependent</code> scope
* returns a null value.
* </p>
*
* <p>
Expand All @@ -73,19 +73,17 @@
*
* <p>
* Many instances of beans with scope <code>@Dependent</code> belong to some other bean or Java EE component class instance and
* are
* called dependent objects.
* are called dependent objects.
* </p>
*
* <ul>
* <li>Instances of decorators and interceptors are dependent objects of the bean instance they decorate.</li>
* <li>An instance of a bean with scope <code>@Dependent</code> injected into a field, bean constructor or initializer method is
* a
* dependent object of the bean or Java EE component class instance into which it was injected.</li>
* a dependent object of the bean or Java EE component class instance into which it was injected.</li>
* <li>An instance of a bean with scope <code>@Dependent</code> injected into a producer method is a dependent object of the
* producer method bean instance that is being produced.</li>
* <li>An instance of a bean with scope <code>@Dependent</code> obtained by direct invocation of an
* {@link Instance} is a dependent object of the instance of {@link Instance}.</li>
* <li>An instance of a bean with scope <code>@Dependent</code> obtained by direct invocation of an {@link Instance} is a
* dependent object of the instance of {@link Instance}.</li>
* </ul>
*
* <p>
Expand Down
21 changes: 9 additions & 12 deletions api/src/main/java/jakarta/enterprise/context/RequestScoped.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,8 @@
* </p>
* <p>
* While <code>RequestScoped</code> 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.
* </p>
*
* <p>
Expand All @@ -45,8 +44,8 @@
*
* <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>ServletRequestListener</code> or <code>AsyncListener</code>,</li>
* of any servlet filter and when the container calls any <code>ServletRequestListener</code> or
* <code>AsyncListener</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
* an EJB timeout method and during message delivery to any EJB message-driven bean, and</li>
Expand All @@ -61,18 +60,16 @@
* <li>at the end of the servlet request, after the <code>service()</code> method, all <code>doFilter()</code> methods, and all
* <code>requestDestroyed()</code> and <code>onComplete()</code> notifications return,</li>
* <li>after the web service invocation completes,</li>
* <li>after the EJB remote method invocation, asynchronous method invocation, timeout or message delivery completes if it
* did not already exist when the invocation occurred, or</li>
* <li>after the EJB remote method invocation, asynchronous method invocation, timeout or message delivery completes if it did
* not already exist when the invocation occurred, or</li>
* <li>after the <code>@PostConstruct</code> callback completes, if it did not already exist when the
* <code>@PostConstruct</code>
* callback occurred.</li>
* <code>@PostConstruct</code> callback occurred.</li>
* </ul>
*
* <p>
* An event with qualifier <code>@Initialized(RequestScoped.class)</code> is fired when the request context is initialized and
* an
* event
* with qualifier <code>@Destroyed(RequestScoped.class)</code> when the request context is destroyed. The event payload is:
* an event with qualifier <code>@Destroyed(RequestScoped.class)</code> when the request context is destroyed. The event payload
* is:
* </p>
*
* <ul>
Expand Down
17 changes: 6 additions & 11 deletions api/src/main/java/jakarta/enterprise/context/SessionScoped.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,8 @@
* </p>
* <p>
* While <code>SessionScoped</code> must be associated with the built-in session 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 session
* context.
* third-party extensions are allowed to also associate it with their own context. Behavior described below is only related to
* the built-in session context.
* </p>
* <p>
* The session scope is active:
Expand All @@ -58,18 +57,14 @@
*
* <ul>
* <li>when the HTTPSession times out, after all <code>HttpSessionListeners</code> have been called, or</li>
* <li>at the very end of
* any request in which <code>invalidate()</code> was called, after all filters and <code>ServletRequestListeners</code> have
* been
* called.</Li>
* <li>at the very end of any request in which <code>invalidate()</code> was called, after all filters and
* <code>ServletRequestListeners</code> have been called.</Li>
* </ul>
*
* <p>
* An event with qualifier <code>@Initialized(SessionScoped.class)</code> is fired when the session context is initialized and
* an
* event
* with qualifier <code>@Destroyed(SessionScoped.class)</code> when the session context is destroyed. The event payload is
* the <code>HttpSession</code>
* an event with qualifier <code>@Destroyed(SessionScoped.class)</code> when the session context is destroyed. The event payload
* is the <code>HttpSession</code>
*
* <p>
* CDI Lite implementations are not required to provide support for the session scope.
Expand Down
6 changes: 3 additions & 3 deletions api/src/main/java/jakarta/enterprise/event/TransactionPhase.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,9 +77,9 @@ public enum TransactionPhase {
* </p>
* <p>
* Transactional observer will be notified will also get invoked if there is no transaction in progress, or the transaction
* is in progress,
* but {@code jakarta.transaction.Synchronization} callback cannot be registered due to the transaction being already
* marked for rollback or in state where {@code jakarta.transaction.Synchronization} callbacks cannot be registered.
* is in progress, but {@code jakarta.transaction.Synchronization} callback cannot be registered due to the transaction
* being already marked for rollback or in state where {@code jakarta.transaction.Synchronization} callbacks cannot be
* registered.
* </p>
*/
AFTER_FAILURE,
Expand Down
4 changes: 2 additions & 2 deletions api/src/main/java/jakarta/enterprise/inject/Alternative.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,8 @@
* <p>
* By default, a bean archive has no selected alternatives. An alternative must be explicitly declared using the
* <code>&lt;alternatives&gt;</code> element of the <code>beans.xml</code> file of the bean archive. The
* <code>&lt;alternatives&gt;</code>
* element contains a list of bean classes and stereotypes. An alternative is selected for the bean archive if either:
* <code>&lt;alternatives&gt;</code> element contains a list of bean classes and stereotypes. An alternative is selected for the
* bean archive if either:
* </p>
*
* <ul>
Expand Down
40 changes: 16 additions & 24 deletions api/src/main/java/jakarta/enterprise/inject/Instance.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,7 @@
* </pre>
*
* <p>
* Or, the {@link Any &#064;Any} qualifier may be used, allowing the application to specify qualifiers
* dynamically:
* Or, the {@link Any &#064;Any} qualifier may be used, allowing the application to specify qualifiers dynamically:
* </p>
*
* <pre>
Expand All @@ -82,10 +81,8 @@
*
* <p>
* The inherited {@link jakarta.inject.Provider#get()} method returns a contextual references for the unique bean that matches
* the
* required type and required qualifiers and is eligible for injection into the class into which the parent
* <code>Instance</code>
* was injected, or throws an {@link UnsatisfiedResolutionException} or
* the required type and required qualifiers and is eligible for injection into the class into which the parent
* <code>Instance</code> was injected, or throws an {@link UnsatisfiedResolutionException} or
* {@link AmbiguousResolutionException}.
* </p>
*
Expand Down Expand Up @@ -126,8 +123,7 @@ public interface Instance<T> extends Iterable<T>, Provider<T> {
* @param qualifiers the additional required qualifiers
* @return the child <code>Instance</code>
* @throws IllegalArgumentException if passed two instances of the same non repeating qualifier type, or an instance of an
* annotation that
* is not a qualifier type
* annotation that is not a qualifier type
* @throws IllegalStateException if the container is already shutdown
*/
Instance<T> select(Annotation... qualifiers);
Expand All @@ -142,8 +138,7 @@ public interface Instance<T> extends Iterable<T>, Provider<T> {
* @param qualifiers the additional required qualifiers
* @return the child <code>Instance</code>
* @throws IllegalArgumentException if passed two instances of the same non repeating qualifier type, or an instance of an
* annotation that
* is not a qualifier type
* annotation that is not a qualifier type
* @throws IllegalStateException if the container is already shutdown
*/
<U extends T> Instance<U> select(Class<U> subtype, Annotation... qualifiers);
Expand All @@ -158,8 +153,7 @@ public interface Instance<T> extends Iterable<T>, Provider<T> {
* @param qualifiers the additional required qualifiers
* @return the child <code>Instance</code>
* @throws IllegalArgumentException if passed two instances of the same non repeating qualifier type, or an instance of an
* annotation that
* is not a qualifier type
* annotation that is not a qualifier type
* @throws IllegalStateException if the container is already shutdown
*/
<U extends T> Instance<U> select(TypeLiteral<U> subtype, Annotation... qualifiers);
Expand Down Expand Up @@ -195,16 +189,15 @@ default Stream<T> stream() {
* </p>
*
* @return <code>true</code> if there is more than one bean that matches the required type and qualifiers and is eligible
* for
* injection into the class into which the parent <code>Instance</code> was injected, or <code>false</code>
* for injection into the class into which the parent <code>Instance</code> was injected, or <code>false</code>
* otherwise.
*/
boolean isAmbiguous();

/**
* <p>
* Determines if there is exactly one bean that matches the required type and qualifiers and is eligible for injection
* into the class into which the parent <code>Instance</code> was injected.
* Determines if there is exactly one bean that matches the required type and qualifiers and is eligible for injection into
* the class into which the parent <code>Instance</code> was injected.
* </p>
*
* @since 2.0
Expand Down Expand Up @@ -236,8 +229,8 @@ default boolean isResolvable() {
void destroy(T instance);

/**
* Obtains an initialized contextual reference handle for a bean that has the required type and qualifiers and is
* eligible for injection. Throws exceptions if there is no such bean or more than one.
* Obtains an initialized contextual reference handle for a bean that has the required type and qualifiers and is eligible
* for injection. Throws exceptions if there is no such bean or more than one.
*
* <p>
* The contextual reference is obtained lazily, i.e. when first needed.
Expand All @@ -251,8 +244,7 @@ default boolean isResolvable() {

/**
* Allows iterating over contextual reference handles for all beans that have the required type and required qualifiers and
* are eligible
* for injection.
* are eligible for injection.
*
* <p>
* Note that the returned {@link Iterable} is stateless. Therefore, each {@link Iterable#iterator()} produces a new set of
Expand All @@ -275,8 +267,8 @@ default Stream<? extends Handle<T>> handlesStream() {
/**
* This interface represents a contextual reference handle.
* <p>
* Allows to inspect the metadata of the relevant bean before resolving its contextual reference and also to destroy
* the underlying contextual instance.
* Allows to inspect the metadata of the relevant bean before resolving its contextual reference and also to destroy the
* underlying contextual instance.
* </p>
*
* @author Matej Novotny
Expand All @@ -290,8 +282,8 @@ interface Handle<T> extends AutoCloseable {
* @return the contextual reference
* @see Instance#get()
* @throws IllegalStateException If the producing {@link Instance} does not exist
* @throws IllegalStateException If invoked on {@link Handle} that previously successfully destroyed its
* underlying contextual reference
* @throws IllegalStateException If invoked on {@link Handle} that previously successfully destroyed its underlying
* contextual reference
*/
T get();

Expand Down
12 changes: 4 additions & 8 deletions api/src/main/java/jakarta/enterprise/inject/Specializes.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,22 +43,18 @@
*
* <p>
* If the second bean has a name, the bean may not declare a name using {@link jakarta.inject.Named &#064;Named}. Furthermore,
* the
* bean must have all the bean types of the second bean.
* the bean must have all the bean types of the second bean.
* </p>
*
* <ul>
* <li>If a bean class of a managed bean is annotated <code>&#064;Specializes</code> , then the bean class must directly extend
* the
* bean class of a second managed bean. Then the first managed bean directly specializes the second managed bean.</li>
* the bean class of a second managed bean. Then the first managed bean directly specializes the second managed bean.</li>
*
* <li>If a bean class of a session bean is annotated <code>&#064;Specializes</code> , then the bean class must directly extend
* the
* bean class of a second session bean. Then the first session bean directly specializes the second session bean.</li>
* the bean class of a second session bean. Then the first session bean directly specializes the second session bean.</li>
*
* <li>If a producer method is annotated <code>&#064;Specializes</code>, then it must be non-static and directly override
* another
* producer method. Then the first producer method directly specializes the second producer method.</li>
* another producer method. Then the first producer method directly specializes the second producer method.</li>
* </ul>
*
* <p>
Expand Down
Loading

0 comments on commit 04bee17

Please sign in to comment.