You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2026/05/11 09:16:34 UTC
(tomcat) branch 11.0.x updated: Fix Jakarta EE APIs javadoc issues
This is an automated email from the ASF dual-hosted git repository.
rmaucher pushed a commit to branch 11.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/11.0.x by this push:
new 9d8b4c99e9 Fix Jakarta EE APIs javadoc issues
9d8b4c99e9 is described below
commit 9d8b4c99e9075901a651fbb3152981a547e96121
Author: remm <re...@apache.org>
AuthorDate: Sat May 9 09:04:07 2026 +0200
Fix Jakarta EE APIs javadoc issues
Includes TODO fixes and a few cut and paste issues.
Coauthored by OpenCode.
One question is if the explicit default constructor will mess up with
the signature validation from the TCK, in which case I will redo it
without that (so I will not backport for now).
---
java/jakarta/annotation/Generated.java | 16 ++-
java/jakarta/annotation/Priority.java | 6 +-
java/jakarta/annotation/Resource.java | 35 +++++--
java/jakarta/annotation/Resources.java | 5 +-
java/jakarta/annotation/security/DeclareRoles.java | 11 +-
java/jakarta/annotation/security/DenyAll.java | 6 ++
java/jakarta/annotation/security/PermitAll.java | 6 ++
java/jakarta/annotation/security/RolesAllowed.java | 12 ++-
java/jakarta/annotation/security/RunAs.java | 10 +-
.../annotation/sql/DataSourceDefinition.java | 95 +++++++++++++----
.../annotation/sql/DataSourceDefinitions.java | 8 +-
java/jakarta/ejb/EJB.java | 38 ++++++-
java/jakarta/ejb/EJBs.java | 11 +-
java/jakarta/el/BeanNameELResolver.java | 8 ++
java/jakarta/el/BeanNameResolver.java | 9 +-
java/jakarta/el/CompositeELResolver.java | 15 +++
java/jakarta/el/ELClass.java | 14 +++
java/jakarta/el/ELContext.java | 50 +++++++++
java/jakarta/el/ELContextEvent.java | 13 +++
java/jakarta/el/ELContextListener.java | 13 +++
java/jakarta/el/ELManager.java | 98 ++++++++++++++++++
java/jakarta/el/ELProcessor.java | 86 +++++++++++++++-
java/jakarta/el/ELResolver.java | 17 +++
java/jakarta/el/EvaluationListener.java | 10 ++
java/jakarta/el/Expression.java | 21 +++-
java/jakarta/el/ExpressionFactory.java | 35 ++++++-
java/jakarta/el/FunctionMapper.java | 24 +++++
java/jakarta/el/ImportHandler.java | 57 ++++++++++-
java/jakarta/el/LambdaExpression.java | 45 ++++++++
java/jakarta/el/ListELResolver.java | 18 ++++
java/jakarta/el/MapELResolver.java | 18 ++++
java/jakarta/el/MethodExpression.java | 16 +++
java/jakarta/el/MethodInfo.java | 29 ++++++
java/jakarta/el/MethodNotFoundException.java | 22 ++++
java/jakarta/el/MethodReference.java | 12 +++
java/jakarta/el/OptionalELResolver.java | 6 ++
java/jakarta/el/PropertyNotFoundException.java | 27 +++++
java/jakarta/el/PropertyNotWritableException.java | 27 +++++
java/jakarta/el/RecordELResolver.java | 7 ++
java/jakarta/el/ResourceBundleELResolver.java | 18 ++++
java/jakarta/el/StandardELContext.java | 29 ++++++
java/jakarta/el/StaticFieldELResolver.java | 11 ++
java/jakarta/el/TypeConverter.java | 11 ++
java/jakarta/el/ValueExpression.java | 33 ++++++
java/jakarta/el/ValueReference.java | 23 +++++
java/jakarta/el/VariableMapper.java | 25 ++++-
java/jakarta/mail/Authenticator.java | 18 ++++
java/jakarta/mail/PasswordAuthentication.java | 12 +++
java/jakarta/mail/Session.java | 22 ++++
java/jakarta/mail/internet/InternetAddress.java | 11 ++
java/jakarta/mail/internet/MimeMessage.java | 19 ++++
java/jakarta/mail/internet/MimePart.java | 4 +
java/jakarta/mail/internet/MimePartDataSource.java | 9 ++
java/jakarta/persistence/PersistenceContext.java | 30 +++++-
.../persistence/PersistenceContextType.java | 16 ++-
java/jakarta/persistence/PersistenceContexts.java | 9 +-
java/jakarta/persistence/PersistenceProperty.java | 15 ++-
java/jakarta/persistence/PersistenceUnit.java | 16 ++-
java/jakarta/persistence/PersistenceUnits.java | 9 +-
java/jakarta/persistence/SynchronizationType.java | 9 ++
.../security/auth/message/AuthException.java | 12 +++
java/jakarta/security/auth/message/AuthStatus.java | 23 +++++
java/jakarta/security/auth/message/ClientAuth.java | 4 +
.../jakarta/security/auth/message/MessageInfo.java | 38 +++++++
.../security/auth/message/MessagePolicy.java | 99 ++++++++++++++++++
java/jakarta/security/auth/message/ServerAuth.java | 7 ++
.../message/callback/CallerPrincipalCallback.java | 34 +++++-
.../auth/message/callback/CertStoreCallback.java | 16 ++-
.../message/callback/GroupPrincipalCallback.java | 19 ++++
.../callback/PasswordValidationCallback.java | 49 ++++++++-
.../auth/message/callback/PrivateKeyCallback.java | 113 +++++++++++++++++++-
.../auth/message/callback/SecretKeyCallback.java | 37 +++++++
.../auth/message/callback/TrustStoreCallback.java | 16 +++
.../security/auth/message/config/AuthConfig.java | 31 ++++++
.../auth/message/config/AuthConfigFactory.java | 112 ++++++++++++++++++++
.../auth/message/config/AuthConfigProvider.java | 30 ++++++
.../auth/message/config/ClientAuthConfig.java | 15 +++
.../auth/message/config/ClientAuthContext.java | 5 +
.../auth/message/config/RegistrationListener.java | 9 ++
.../auth/message/config/ServerAuthConfig.java | 12 +++
.../auth/message/config/ServerAuthContext.java | 7 ++
.../auth/message/module/ClientAuthModule.java | 21 ++++
.../auth/message/module/ServerAuthModule.java | 25 +++++
java/jakarta/servlet/AsyncContext.java | 34 ++++--
java/jakarta/servlet/GenericFilter.java | 13 ++-
java/jakarta/servlet/HttpConstraintElement.java | 12 +--
java/jakarta/servlet/ServletContext.java | 84 ++++++++++-----
java/jakarta/servlet/ServletRequest.java | 53 ++++++----
java/jakarta/servlet/ServletRequestWrapper.java | 8 +-
java/jakarta/servlet/ServletResponseWrapper.java | 6 +-
java/jakarta/servlet/annotation/HandlesTypes.java | 8 +-
.../servlet/annotation/MultipartConfig.java | 9 ++
java/jakarta/servlet/annotation/WebFilter.java | 22 +++-
java/jakarta/servlet/annotation/WebInitParam.java | 6 ++
java/jakarta/servlet/annotation/WebListener.java | 2 +
java/jakarta/servlet/annotation/WebServlet.java | 86 ++++++++++------
java/jakarta/servlet/http/HttpFilter.java | 7 ++
java/jakarta/servlet/http/HttpServletMapping.java | 36 ++++---
java/jakarta/servlet/http/PushBuilder.java | 6 +-
.../transaction/HeuristicCommitException.java | 14 +++
.../transaction/HeuristicMixedException.java | 14 +++
.../transaction/HeuristicRollbackException.java | 14 +++
.../transaction/InvalidTransactionException.java | 13 +++
.../jakarta/transaction/NotSupportedException.java | 11 ++
java/jakarta/transaction/RollbackException.java | 11 ++
java/jakarta/transaction/Status.java | 33 ++++++
java/jakarta/transaction/Synchronization.java | 17 +++
java/jakarta/transaction/SystemException.java | 21 ++++
java/jakarta/transaction/Transaction.java | 63 ++++++++++++
java/jakarta/transaction/TransactionManager.java | 68 ++++++++++++
.../transaction/TransactionRequiredException.java | 11 ++
.../TransactionRolledbackException.java | 11 ++
.../TransactionSynchronizationRegistry.java | 40 ++++++++
java/jakarta/transaction/UserTransaction.java | 47 +++++++++
java/jakarta/websocket/ClientEndpoint.java | 25 +++++
java/jakarta/websocket/ClientEndpointConfig.java | 82 +++++++++++++++
java/jakarta/websocket/CloseReason.java | 106 +++++++++++++++++++
java/jakarta/websocket/ContainerProvider.java | 11 ++
java/jakarta/websocket/DecodeException.java | 45 ++++++++
java/jakarta/websocket/Decoder.java | 68 ++++++++++++
java/jakarta/websocket/DeploymentException.java | 14 +++
java/jakarta/websocket/EncodeException.java | 24 +++++
java/jakarta/websocket/Encoder.java | 58 ++++++++++-
java/jakarta/websocket/Endpoint.java | 10 ++
java/jakarta/websocket/EndpointConfig.java | 19 ++++
java/jakarta/websocket/Extension.java | 28 +++++
java/jakarta/websocket/HandshakeResponse.java | 8 ++
java/jakarta/websocket/MessageHandler.java | 16 +++
java/jakarta/websocket/OnClose.java | 4 +
java/jakarta/websocket/OnError.java | 4 +
java/jakarta/websocket/OnMessage.java | 11 ++
java/jakarta/websocket/OnOpen.java | 4 +
java/jakarta/websocket/RemoteEndpoint.java | 22 ++++
java/jakarta/websocket/SendHandler.java | 8 ++
java/jakarta/websocket/SendResult.java | 14 +++
java/jakarta/websocket/Session.java | 83 +++++++++++++++
java/jakarta/websocket/SessionException.java | 18 ++++
java/jakarta/websocket/WebSocketContainer.java | 22 ++++
.../jakarta/websocket/server/HandshakeRequest.java | 44 ++++++++
java/jakarta/websocket/server/PathParam.java | 6 ++
java/jakarta/websocket/server/ServerContainer.java | 13 +++
java/jakarta/websocket/server/ServerEndpoint.java | 25 +++++
.../websocket/server/ServerEndpointConfig.java | 114 +++++++++++++++++++++
java/jakarta/xml/ws/WebServiceRef.java | 31 +++++-
java/jakarta/xml/ws/WebServiceRefs.java | 11 +-
145 files changed, 3585 insertions(+), 182 deletions(-)
diff --git a/java/jakarta/annotation/Generated.java b/java/jakarta/annotation/Generated.java
index 19cbed8bc6..8251be3970 100644
--- a/java/jakarta/annotation/Generated.java
+++ b/java/jakarta/annotation/Generated.java
@@ -33,18 +33,26 @@ import java.lang.annotation.Target;
@Retention(RetentionPolicy.SOURCE)
public @interface Generated {
/**
- * @return The name of the code generator. It is recommended that the fully qualified name of the code generator is
- * used.
+ * Specifies the name(s) of the tool(s) that generated the annotated element.
+ * It is recommended that the fully qualified name of the code generator is used.
+ *
+ * @return the array of code generator names
*/
String[] value();
/**
- * @return The date the code was generated
+ * Specifies the date and time when the code was generated, typically in
+ * ISO 8601 format. An empty string indicates the date is not specified.
+ *
+ * @return the code generation date, or an empty string if not specified
*/
String date() default "";
/**
- * @return Additional comments (if any) related to the code generation
+ * Provides additional comments or metadata related to the code generation
+ * process, such as version information or configuration details.
+ *
+ * @return additional comments about the code generation, or an empty string if none
*/
String comments() default "";
}
diff --git a/java/jakarta/annotation/Priority.java b/java/jakarta/annotation/Priority.java
index c44be40d7f..4809275165 100644
--- a/java/jakarta/annotation/Priority.java
+++ b/java/jakarta/annotation/Priority.java
@@ -31,7 +31,11 @@ import java.lang.annotation.RetentionPolicy;
public @interface Priority {
/**
- * @return the int value
+ * Specifies the priority value used to determine the ordering of the annotated
+ * element. Lower values indicate higher priority. The annotated class or
+ * parameter defines how the priority value is interpreted and applied.
+ *
+ * @return the priority ordering value
*/
int value();
}
diff --git a/java/jakarta/annotation/Resource.java b/java/jakarta/annotation/Resource.java
index 692d13418e..a66f5fc621 100644
--- a/java/jakarta/annotation/Resource.java
+++ b/java/jakarta/annotation/Resource.java
@@ -48,7 +48,10 @@ public @interface Resource {
}
/**
- * @return a String with the name of the resource
+ * Specifies the logical name of the resource. If not specified, the container
+ * derives the name from the field or method to which the annotation is applied.
+ *
+ * @return the logical name of the resource
*/
String name() default "";
@@ -60,29 +63,49 @@ public @interface Resource {
Class<?> type() default Object.class;
/**
- * @return the AuthenticationType of the resource default CONTAINER
+ * Specifies the authentication type for the resource. Container authentication
+ * means the container handles authentication, while application authentication
+ * means the application code is responsible for authentication.
+ *
+ * @return the authentication type, defaulting to {@link AuthenticationType#CONTAINER}
*/
AuthenticationType authenticationType() default AuthenticationType.CONTAINER;
/**
- * @return true (default) if the resource is shareable, or false if not
+ * Indicates whether the resource can be shared among multiple injection points.
+ * When true, the same resource instance may be injected into multiple components.
+ * When false, each injection point receives a distinct resource instance.
+ *
+ * @return true if the resource is shareable across injection points, false otherwise
*/
boolean shareable() default true;
/**
- * @return a string with the description for the resource
+ * Provides a human-readable description of the resource for documentation
+ * and administrative purposes.
+ *
+ * @return the resource description
*/
String description() default "";
/**
- * @return a string with the mappedName of the resource
+ * Specifies a product-dependent name for the resource, allowing the container
+ * to map the logical resource name to a physical resource in a vendor-specific
+ * manner. This is typically used for environment-specific configuration.
+ *
+ * @return the product-specific mapped name for the resource
*/
String mappedName() default "";
/**
+ * Specifies the JNDI lookup name for the resource. This attribute allows
+ * explicit control over the JNDI name used to locate the resource, overriding
+ * the default name derivation. The lookup name is typically prefixed with
+ * "java:comp/env/" for component environment entries.
+ *
* @since Common Annotations 1.1
*
- * @return The name of the entry, if any, to use for this resource
+ * @return the JNDI lookup name for the resource
*/
String lookup() default "";
}
diff --git a/java/jakarta/annotation/Resources.java b/java/jakarta/annotation/Resources.java
index 6ade76d6a6..bf668c6f1f 100644
--- a/java/jakarta/annotation/Resources.java
+++ b/java/jakarta/annotation/Resources.java
@@ -33,7 +33,10 @@ import java.lang.annotation.Target;
public @interface Resources {
/**
- * @return a Resource[] with the value of this Resources
+ * Specifies the array of {@link Resource} annotations that define the resources
+ * required by the annotated component.
+ *
+ * @return the array of resource definitions
*/
Resource[] value();
}
diff --git a/java/jakarta/annotation/security/DeclareRoles.java b/java/jakarta/annotation/security/DeclareRoles.java
index 3762af6a94..434aea50fd 100644
--- a/java/jakarta/annotation/security/DeclareRoles.java
+++ b/java/jakarta/annotation/security/DeclareRoles.java
@@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
+ * Declares that role names used in security constraints for the annotated
+ * enterprise bean should be treated as declared roles. When this annotation
+ * is present, the container must create any roles referenced in security
+ * constraints that are not explicitly defined in the deployment descriptor.
+ *
* @since Common Annotations 1.0
*/
@Documented
@@ -31,7 +36,11 @@ import java.lang.annotation.Target;
public @interface DeclareRoles {
/**
- * @return a String[] with the roles
+ * Specifies the declared role names that should be recognized by the container.
+ * These roles may be referenced in security constraints without being explicitly
+ * defined in the deployment descriptor.
+ *
+ * @return the array of declared role names
*/
String[] value();
}
diff --git a/java/jakarta/annotation/security/DenyAll.java b/java/jakarta/annotation/security/DenyAll.java
index 9944210ce7..10db8d2a76 100644
--- a/java/jakarta/annotation/security/DenyAll.java
+++ b/java/jakarta/annotation/security/DenyAll.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
+ * Indicates that all access to the annotated enterprise bean or business method
+ * is denied. When applied at the class level, all security roles are prohibited
+ * from invoking any business method of the bean. When applied at the method level,
+ * the specified method is inaccessible to all roles. This annotation takes
+ * precedence over {@link PermitAll} and {@link RolesAllowed}.
+ *
* @since Common Annotations 1.0
*/
@Documented
diff --git a/java/jakarta/annotation/security/PermitAll.java b/java/jakarta/annotation/security/PermitAll.java
index 0e0c784c65..d129f8f2bc 100644
--- a/java/jakarta/annotation/security/PermitAll.java
+++ b/java/jakarta/annotation/security/PermitAll.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
+ * Indicates that all authenticated users are permitted to access the annotated
+ * enterprise bean or business method. When applied at the class level, any
+ * authenticated user may invoke any business method of the bean. When applied
+ * at the method level, the specified method is accessible to all authenticated
+ * users. This annotation takes precedence over {@link RolesAllowed}.
+ *
* @since Common Annotations 1.0
*/
@Documented
diff --git a/java/jakarta/annotation/security/RolesAllowed.java b/java/jakarta/annotation/security/RolesAllowed.java
index 7092d01ab3..48b003de31 100644
--- a/java/jakarta/annotation/security/RolesAllowed.java
+++ b/java/jakarta/annotation/security/RolesAllowed.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
+ * Specifies the security roles that are allowed to access the annotated enterprise
+ * bean or business method. When applied at the class level, only the listed roles
+ * may invoke any business method of the bean. When applied at the method level,
+ * only the listed roles may invoke the specified method. This annotation is
+ * mutually exclusive with {@link PermitAll} and {@link DenyAll}.
+ *
* @since Common Annotations 1.0
*/
@Documented
@@ -31,7 +37,11 @@ import java.lang.annotation.Target;
public @interface RolesAllowed {
/**
- * @return a String[] of the allowed roles
+ * Specifies the security role names that are authorized to access the
+ * annotated component or method. Only callers assigned one of these roles
+ * will be permitted access.
+ *
+ * @return the array of authorized role names
*/
String[] value();
}
diff --git a/java/jakarta/annotation/security/RunAs.java b/java/jakarta/annotation/security/RunAs.java
index d5029b7ecc..8d935eb51c 100644
--- a/java/jakarta/annotation/security/RunAs.java
+++ b/java/jakarta/annotation/security/RunAs.java
@@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
+ * Defines the run-as security role for an enterprise bean. The container assumes
+ * the specified role as the caller identity for all business method invocations
+ * made by the bean, regardless of the actual caller's identity. This allows the
+ * bean to access resources with a consistent security context.
+ *
* @since Common Annotations 1.0
*/
@Documented
@@ -31,7 +36,10 @@ import java.lang.annotation.Target;
public @interface RunAs {
/**
- * @return a String with the value for RunAs
+ * Specifies the security role name that the container should assume as the
+ * caller identity when executing business methods on behalf of this component.
+ *
+ * @return the run-as role name
*/
String value();
}
diff --git a/java/jakarta/annotation/sql/DataSourceDefinition.java b/java/jakarta/annotation/sql/DataSourceDefinition.java
index 9e5c46d0f3..0bea20aa2b 100644
--- a/java/jakarta/annotation/sql/DataSourceDefinition.java
+++ b/java/jakarta/annotation/sql/DataSourceDefinition.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
+ * Defines a data source for dependency injection via the {@link jakarta.annotation.Resource}
+ * annotation. This annotation allows developers to declaratively specify the properties
+ * of a JDBC data source, including connection details, pool sizing, and transactional
+ * behavior. The container creates and manages the data source based on the specified
+ * configuration, making it available for injection into application components.
+ *
* @since Common Annotations 1.1
*/
@Target(ElementType.TYPE)
@@ -31,92 +37,145 @@ import java.lang.annotation.Target;
public @interface DataSourceDefinition {
/**
- * @return the className
+ * Specifies the fully qualified class name of the JDBC driver or the Jakarta
+ * Connector connection factory class that implements this data source.
+ *
+ * @return the fully qualified class name of the data source implementation
*/
String className();
/**
- * @return the name
+ * Specifies the JNDI name under which the data source will be registered.
+ * This is the lookup name used for dependency injection or explicit JNDI
+ * lookup of the data source.
+ *
+ * @return the JNDI name for the data source
*/
String name();
/**
- * @return the description
+ * Provides a human-readable description of the data source for documentation
+ * and administrative purposes.
+ *
+ * @return the description of the data source
*/
String description() default "";
/**
- * @return the url
+ * Specifies the JDBC connection URL for the database. This URL is used by
+ * the driver to establish connections to the database server.
+ *
+ * @return the JDBC connection URL
*/
String url() default "";
/**
- * @return the user
+ * Specifies the database user name used to establish connections.
+ *
+ * @return the database user name
*/
String user() default "";
/**
- * @return the password
+ * Specifies the password for the database user account used to establish connections.
+ *
+ * @return the database password
*/
String password() default "";
/**
- * @return database name
+ * Specifies the name of the database to connect to. This is used in conjunction
+ * with the server name and port number to locate the target database.
+ *
+ * @return the database name
*/
String databaseName() default "";
/**
- * @return the port number
+ * Specifies the network port number on which the database server is listening.
+ * A value of -1 indicates the default port for the database type.
+ *
+ * @return the database server port number, or -1 for the default
*/
int portNumber() default -1;
/**
- * @return the server name
+ * Specifies the host name or IP address of the database server.
+ *
+ * @return the database server host name, defaulting to "localhost"
*/
String serverName() default "localhost";
/**
- * @return the isolation level
+ * Specifies the transaction isolation level for connections from this data source,
+ * using the constants defined in {@link java.sql.Connection}. A value of -1
+ * indicates the database default isolation level should be used.
+ *
+ * @return the transaction isolation level, or -1 for the database default
*/
int isolationLevel() default -1;
/**
- * @return true if the data source is transactional
+ * Indicates whether connections from this data source support container-managed
+ * transactions. When true, the data source participates in Jakarta Transactions.
+ *
+ * @return true if the data source participates in container-managed transactions
*/
boolean transactional() default true;
/**
- * @return the initial pool size
+ * Specifies the number of connections to create when the connection pool is
+ * initialized. A value of -1 indicates the container default should be used.
+ *
+ * @return the initial number of connections in the pool, or -1 for default
*/
int initialPoolSize() default -1;
/**
- * @return the max pool size
+ * Specifies the maximum number of connections that the pool may create.
+ * A value of -1 indicates the container default should be used.
+ *
+ * @return the maximum pool size, or -1 for the container default
*/
int maxPoolSize() default -1;
/**
- * @return the min pool size
+ * Specifies the minimum number of connections that the pool must maintain.
+ * A value of -1 indicates the container default should be used.
+ *
+ * @return the minimum pool size, or -1 for the container default
*/
int minPoolSize() default -1;
/**
- * @return the max idle time
+ * Specifies the maximum idle time in seconds before a connection is closed
+ * and removed from the pool. A value of -1 indicates no idle timeout.
+ *
+ * @return the maximum idle time in seconds, or -1 for no timeout
*/
int maxIdleTime() default -1;
/**
- * @return the max statements
+ * Specifies the maximum number of prepared statements that may be cached
+ * per connection in the pool. A value of -1 indicates the container default.
+ *
+ * @return the maximum cached prepared statements per connection, or -1 for default
*/
int maxStatements() default -1;
/**
- * @return a String[] with the properties
+ * Specifies additional connection properties in the form "name=value" strings.
+ * These properties are passed to the JDBC driver during connection establishment.
+ *
+ * @return the array of additional connection properties
*/
String[] properties() default {};
/**
- * @return the login timeout
+ * Specifies the maximum time in seconds that the driver will wait when
+ * attempting to connect to the database. A value of 0 means no timeout.
+ *
+ * @return the login timeout in seconds, or 0 for no timeout
*/
int loginTimeout() default 0;
}
diff --git a/java/jakarta/annotation/sql/DataSourceDefinitions.java b/java/jakarta/annotation/sql/DataSourceDefinitions.java
index d40e357af5..ace5402e7a 100644
--- a/java/jakarta/annotation/sql/DataSourceDefinitions.java
+++ b/java/jakarta/annotation/sql/DataSourceDefinitions.java
@@ -22,6 +22,10 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
+ * Container annotation that holds multiple {@link DataSourceDefinition} annotations.
+ * This annotation is used to group several data source definitions when applied to
+ * the same type, following the standard Java annotation repetition pattern.
+ *
* @since Common Annotations 1.1
*/
@Target(ElementType.TYPE)
@@ -29,7 +33,9 @@ import java.lang.annotation.Target;
public @interface DataSourceDefinitions {
/**
- * @return a DataSourceDefinition[]
+ * Specifies the array of data source definitions contained within this container annotation.
+ *
+ * @return the array of {@link DataSourceDefinition} annotations
*/
DataSourceDefinition[] value();
}
diff --git a/java/jakarta/ejb/EJB.java b/java/jakarta/ejb/EJB.java
index cd5b24720c..94fab54075 100644
--- a/java/jakarta/ejb/EJB.java
+++ b/java/jakarta/ejb/EJB.java
@@ -21,20 +21,56 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Declares a dependency on an enterprise bean. The EJB annotation can be applied to a field or method to inject
+ * a reference to an enterprise bean, or to a class to declare bean dependencies for the entire bean.
+ */
@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
-
public @interface EJB {
+
+ /**
+ * The name element for the annotation. The name of an enterprise bean is relative to the javax.np.Context of
+ * the bean. The name must be unique within the bean.
+ *
+ * @return the name of the enterprise bean
+ */
String name() default "";
+ /**
+ * A description of the enterprise bean reference.
+ *
+ * @return the description
+ */
String description() default "";
+ /**
+ * The interface of the enterprise bean.
+ *
+ * @return the bean interface class
+ */
@SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
Class beanInterface() default Object.class;
+ /**
+ * The name of the enterprise bean. The beanName is relative to the javax.naming.Context of the bean that
+ * owns this reference.
+ *
+ * @return the name of the enterprise bean
+ */
String beanName() default "";
+ /**
+ * A provider-specific name that this reference should be mapped to. The entire name is provider-specific.
+ *
+ * @return the provider-specific mapped name
+ */
String mappedName() default "";
+ /**
+ * A JNDI name used to locate the enterprise bean. The lookup element overrides the default JNDI lookup name.
+ *
+ * @return the JNDI lookup string
+ */
String lookup() default "";
}
diff --git a/java/jakarta/ejb/EJBs.java b/java/jakarta/ejb/EJBs.java
index 5f2647cb17..2457371609 100644
--- a/java/jakarta/ejb/EJBs.java
+++ b/java/jakarta/ejb/EJBs.java
@@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Groups multiple {@link EJB} annotations on a single declaration. Use this annotation when a class has dependencies
+ * on more than one enterprise bean.
+ */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-
public @interface EJBs {
+
+ /**
+ * The array of EJB annotations.
+ *
+ * @return the EJB annotations
+ */
EJB[] value();
}
diff --git a/java/jakarta/el/BeanNameELResolver.java b/java/jakarta/el/BeanNameELResolver.java
index 8331e310f4..248b08fe4f 100644
--- a/java/jakarta/el/BeanNameELResolver.java
+++ b/java/jakarta/el/BeanNameELResolver.java
@@ -19,12 +19,20 @@ package jakarta.el;
import java.util.Objects;
/**
+ * ELResolver that resolves bean names to bean instances using a {@link BeanNameResolver}. This resolver handles
+ * expressions where the base is {@code null} and the property is a {@link String} representing a bean name.
+ *
* @since EL 3.0
*/
public class BeanNameELResolver extends ELResolver {
private final BeanNameResolver beanNameResolver;
+ /**
+ * Constructs a BeanNameELResolver with the specified BeanNameResolver.
+ *
+ * @param beanNameResolver the resolver used to look up beans by name
+ */
public BeanNameELResolver(BeanNameResolver beanNameResolver) {
this.beanNameResolver = beanNameResolver;
}
diff --git a/java/jakarta/el/BeanNameResolver.java b/java/jakarta/el/BeanNameResolver.java
index 17754a1553..c8ab3a8661 100644
--- a/java/jakarta/el/BeanNameResolver.java
+++ b/java/jakarta/el/BeanNameResolver.java
@@ -18,12 +18,19 @@ package jakarta.el;
/**
* Base implementation that provides a minimal default implementation that is intended to be extended by application
- * developers.
+ * developers. Subclasses define the logic for resolving bean names to bean instances, checking read-only status,
+ * and determining whether new beans can be created.
*
* @since EL 3.0
*/
public abstract class BeanNameResolver {
+ /**
+ * Default constructor for subclasses.
+ */
+ public BeanNameResolver() {
+ }
+
/**
* Can this resolver resolve the given bean name?
*
diff --git a/java/jakarta/el/CompositeELResolver.java b/java/jakarta/el/CompositeELResolver.java
index 8c9c1fc335..4a73d13d72 100644
--- a/java/jakarta/el/CompositeELResolver.java
+++ b/java/jakarta/el/CompositeELResolver.java
@@ -20,6 +20,11 @@ import java.util.HashSet;
import java.util.Objects;
import java.util.Set;
+/**
+ * ELResolver that delegates to an ordered list of other ELResolvers. When a property operation is performed, each
+ * contained resolver is invoked in order until one resolves the property. This is the standard mechanism for
+ * building a resolver chain in an EL context.
+ */
public class CompositeELResolver extends ELResolver {
private static final Class<?> SCOPED_ATTRIBUTE_EL_RESOLVER;
@@ -62,6 +67,9 @@ public class CompositeELResolver extends ELResolver {
private int typeConvertersSize;
private ELResolver[] typeConverters;
+ /**
+ * Constructs an empty CompositeELResolver. Use {@link #add(ELResolver)} to add resolvers to the chain.
+ */
public CompositeELResolver() {
resolversSize = 0;
resolvers = new ELResolver[8];
@@ -70,6 +78,13 @@ public class CompositeELResolver extends ELResolver {
typeConverters = new ELResolver[0];
}
+ /**
+ * Adds an ELResolver to the end of the resolver chain.
+ *
+ * @param elResolver the resolver to add
+ *
+ * @throws NullPointerException if elResolver is {@code null}
+ */
public void add(ELResolver elResolver) {
Objects.requireNonNull(elResolver);
diff --git a/java/jakarta/el/ELClass.java b/java/jakarta/el/ELClass.java
index 0d003029ec..d72fd9bf0e 100644
--- a/java/jakarta/el/ELClass.java
+++ b/java/jakarta/el/ELClass.java
@@ -17,16 +17,30 @@
package jakarta.el;
/**
+ * Wrapper for a {@link Class} object that enables access to static fields and methods from EL expressions. An
+ * ELClass instance is used as the base object when resolving static members, typically in conjunction with the
+ * {@link StaticFieldELResolver}.
+ *
* @since EL 3.0
*/
public class ELClass {
private final Class<?> clazz;
+ /**
+ * Constructs an ELClass wrapping the specified Class.
+ *
+ * @param clazz the class to wrap
+ */
public ELClass(Class<?> clazz) {
this.clazz = clazz;
}
+ /**
+ * Returns the wrapped Class.
+ *
+ * @return the wrapped Class
+ */
public Class<?> getKlass() {
return clazz;
}
diff --git a/java/jakarta/el/ELContext.java b/java/jakarta/el/ELContext.java
index f99f82c0f7..d0f7e4adbe 100644
--- a/java/jakarta/el/ELContext.java
+++ b/java/jakarta/el/ELContext.java
@@ -28,6 +28,11 @@ import java.util.Locale;
import java.util.Map;
import java.util.Objects;
+/**
+ * Provides the context in which an EL expression is evaluated. An ELContext holds references to the
+ * {@link ELResolver}, {@link FunctionMapper}, {@link VariableMapper}, {@link ImportHandler}, locale, and other
+ * objects required for expression evaluation. Implementations include {@link StandardELContext}.
+ */
public abstract class ELContext {
private Locale locale;
@@ -42,6 +47,9 @@ public abstract class ELContext {
private Deque<Map<String,Object>> lambdaArguments = null;
+ /**
+ * Constructs an ELContext with the resolved flag set to {@code false}.
+ */
public ELContext() {
this.resolved = false;
}
@@ -53,6 +61,13 @@ public abstract class ELContext {
return lambdaArguments;
}
+ /**
+ * Sets the internal flag indicating whether a property has been resolved during the current
+ * evaluation step. This method is used by {@link ELResolver} implementations to signal that
+ * they have handled the current base/property combination.
+ *
+ * @param resolved {@code true} if a property has been resolved, {@code false} otherwise
+ */
public void setPropertyResolved(boolean resolved) {
this.resolved = resolved;
}
@@ -70,6 +85,13 @@ public abstract class ELContext {
notifyPropertyResolved(base, property);
}
+ /**
+ * Returns whether a property has been resolved during the current evaluation step.
+ * ELResolver implementations call {@link #setPropertyResolved(boolean)} to indicate resolution,
+ * and the expression evaluator checks this flag to determine if resolution was successful.
+ *
+ * @return {@code true} if a property has been resolved, {@code false} otherwise
+ */
public boolean isPropertyResolved() {
return this.resolved;
}
@@ -110,6 +132,11 @@ public abstract class ELContext {
return this.map.get(key);
}
+ /**
+ * Returns the ELResolver used to resolve properties and method invocations during expression evaluation.
+ *
+ * @return the ELResolver for this context
+ */
public abstract ELResolver getELResolver();
/**
@@ -126,16 +153,39 @@ public abstract class ELContext {
return importHandler;
}
+ /**
+ * Returns the FunctionMapper used to resolve EL function names to Java methods during expression evaluation.
+ *
+ * @return the FunctionMapper for this context
+ */
public abstract FunctionMapper getFunctionMapper();
+ /**
+ * Returns the locale associated with this EL context. The locale is used for type conversion
+ * operations such as parsing numbers and dates during expression evaluation.
+ *
+ * @return the locale for this context, or {@code null} if not set
+ */
public Locale getLocale() {
return this.locale;
}
+ /**
+ * Sets the locale for this EL context. The locale is used for type conversion operations
+ * such as parsing numbers and dates during expression evaluation.
+ *
+ * @param locale the locale to use for this context
+ */
public void setLocale(Locale locale) {
this.locale = locale;
}
+ /**
+ * Returns the VariableMapper used to resolve EL variable names to {@link ValueExpression}
+ * instances during expression evaluation.
+ *
+ * @return the VariableMapper for this context
+ */
public abstract VariableMapper getVariableMapper();
/**
diff --git a/java/jakarta/el/ELContextEvent.java b/java/jakarta/el/ELContextEvent.java
index b5bfda0e68..713e668b5e 100644
--- a/java/jakarta/el/ELContextEvent.java
+++ b/java/jakarta/el/ELContextEvent.java
@@ -19,18 +19,31 @@ package jakarta.el;
import java.io.Serial;
import java.util.EventObject;
+/**
+ * Event object passed to {@link ELContextListener} instances when an EL context is created or
+ * released. The source of this event is the {@link ELContext} that was created or released.
+ *
+ * @since EL 2.1
+ */
public class ELContextEvent extends EventObject {
@Serial
private static final long serialVersionUID = 1255131906285426769L;
/**
+ * Constructs an ELContextEvent with the specified ELContext as its source.
+ *
* @param source The EL context that was the source of this event
*/
public ELContextEvent(ELContext source) {
super(source);
}
+ /**
+ * Returns the ELContext that is the source of this event.
+ *
+ * @return the ELContext associated with this event
+ */
public ELContext getELContext() {
return (ELContext) this.getSource();
}
diff --git a/java/jakarta/el/ELContextListener.java b/java/jakarta/el/ELContextListener.java
index d161362da7..31fb003165 100644
--- a/java/jakarta/el/ELContextListener.java
+++ b/java/jakarta/el/ELContextListener.java
@@ -16,8 +16,21 @@
*/
package jakarta.el;
+/**
+ * Listener interface for EL context lifecycle events. Implementations are notified when an
+ * {@link ELContext} is created or released, allowing them to perform initialization or
+ * cleanup operations on the context.
+ *
+ * @since EL 2.1
+ */
public interface ELContextListener extends java.util.EventListener {
+ /**
+ * Notification that an EL context has been created. Implementations can use this callback
+ * to register resources, resolvers, or other objects with the newly created context.
+ *
+ * @param event the event containing the ELContext that was created
+ */
void contextCreated(ELContextEvent event);
}
diff --git a/java/jakarta/el/ELManager.java b/java/jakarta/el/ELManager.java
index 4f552942cf..ae16a33909 100644
--- a/java/jakarta/el/ELManager.java
+++ b/java/jakarta/el/ELManager.java
@@ -20,16 +20,38 @@ import java.lang.reflect.Method;
import java.util.Map;
/**
+ * Provides a simplified API for managing EL context, resolvers, functions, and variables. This class maintains a
+ * {@link StandardELContext} and provides convenience methods for adding resolvers, mapping functions, setting
+ * variables, and managing imports. It is used internally by {@link ELProcessor}.
+ *
* @since EL 3.0
*/
public class ELManager {
private StandardELContext context = null;
+ /**
+ * Constructs an ELManager with a lazily initialized {@link StandardELContext}.
+ */
+ public ELManager() {
+ }
+
+ /**
+ * Returns the {@link ExpressionFactory} used to create and evaluate EL expressions.
+ * The factory is obtained through the standard service discovery mechanism.
+ *
+ * @return the ExpressionFactory instance
+ */
public static ExpressionFactory getExpressionFactory() {
return Util.getExpressionFactory();
}
+ /**
+ * Returns the {@link StandardELContext} managed by this ELManager, creating it on first access
+ * if it does not already exist.
+ *
+ * @return the StandardELContext instance
+ */
public StandardELContext getELContext() {
if (context == null) {
context = new StandardELContext(getExpressionFactory());
@@ -38,40 +60,110 @@ public class ELManager {
return context;
}
+ /**
+ * Replaces the current EL context with a new {@link StandardELContext} initialized from the
+ * given context. The new context copies the ELResolver chain, FunctionMapper, VariableMapper,
+ * and other settings from the provided context.
+ *
+ * @param context the ELContext from which to initialize the new context
+ *
+ * @return the previous StandardELContext, or {@code null} if none existed
+ */
public ELContext setELContext(ELContext context) {
StandardELContext oldContext = this.context;
this.context = new StandardELContext(context);
return oldContext;
}
+ /**
+ * Adds a {@link BeanNameELResolver} to the resolver chain that uses the given
+ * {@link BeanNameResolver} to resolve top-level identifiers to managed beans.
+ *
+ * @param beanNameResolver the resolver for bean names
+ */
public void addBeanNameResolver(BeanNameResolver beanNameResolver) {
getELContext().addELResolver(new BeanNameELResolver(beanNameResolver));
}
+ /**
+ * Adds an {@link ELResolver} to the front of the resolver chain in the managed EL context.
+ * Resolvers added first have higher priority during property resolution.
+ *
+ * @param resolver the ELResolver to add
+ */
public void addELResolver(ELResolver resolver) {
getELContext().addELResolver(resolver);
}
+ /**
+ * Maps a static method to an EL function name with the given prefix and local name.
+ * The function can then be invoked in EL expressions as {@code prefix:function(args)}.
+ *
+ * @param prefix the namespace prefix for the function
+ * @param function the local function name
+ * @param method the static {@link java.lang.reflect.Method} to map
+ */
public void mapFunction(String prefix, String function, Method method) {
getELContext().getFunctionMapper().mapFunction(prefix, function, method);
}
+ /**
+ * Registers a variable in the EL context's variable mapper. The variable can then be
+ * referenced by name in EL expressions. Passing a {@code null} expression removes
+ * the variable.
+ *
+ * @param variable the variable name
+ * @param expression the ValueExpression associated with the variable, or {@code null} to remove
+ */
public void setVariable(String variable, ValueExpression expression) {
getELContext().getVariableMapper().setVariable(variable, expression);
}
+ /**
+ * Imports a static field or method so it can be referenced by its simple name in EL
+ * expressions. The argument must be a fully qualified name in the form
+ * {@code className.staticMemberName}.
+ *
+ * @param staticMemberName the fully qualified name of the static member to import
+ *
+ * @throws ELException if the static member cannot be found or is ambiguous
+ */
public void importStatic(String staticMemberName) throws ELException {
getELContext().getImportHandler().importStatic(staticMemberName);
}
+ /**
+ * Imports a class so it can be referenced by its simple name in EL expressions.
+ * The argument must be a fully qualified class name.
+ *
+ * @param className the fully qualified class name to import
+ *
+ * @throws ELException if the class name is invalid or conflicts with an existing import
+ */
public void importClass(String className) throws ELException {
getELContext().getImportHandler().importClass(className);
}
+ /**
+ * Imports all classes from a package so they can be referenced by their simple names
+ * in EL expressions.
+ *
+ * @param packageName the package name to import
+ */
public void importPackage(String packageName) {
getELContext().getImportHandler().importPackage(packageName);
}
+ /**
+ * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
+ * is provided, it is stored under the given name. When {@code null} is provided, the
+ * bean with the given name is removed.
+ *
+ * @param name the bean name
+ * @param bean the bean object to define, or {@code null} to remove the bean
+ *
+ * @return the previous bean associated with the name, or {@code null} if there was none
+ */
public Object defineBean(String name, Object bean) {
Map<String,Object> localBeans = getELContext().getLocalBeans();
@@ -82,6 +174,12 @@ public class ELManager {
}
}
+ /**
+ * Registers an {@link EvaluationListener} with the managed EL context. The listener
+ * will be notified before and after expression evaluation, and when properties are resolved.
+ *
+ * @param listener the EvaluationListener to register
+ */
public void addEvaluationListener(EvaluationListener listener) {
getELContext().addEvaluationListener(listener);
}
diff --git a/java/jakarta/el/ELProcessor.java b/java/jakarta/el/ELProcessor.java
index d3f10f17b9..0b3795116e 100644
--- a/java/jakarta/el/ELProcessor.java
+++ b/java/jakarta/el/ELProcessor.java
@@ -22,6 +22,10 @@ import java.util.HashSet;
import java.util.Set;
/**
+ * Provides a simple API for evaluating EL expressions in a standalone environment. This class wraps an
+ * {@link ELManager} and provides methods for evaluating expressions, defining beans and functions, and managing
+ * variables. It is the primary entry point for applications that use the EL API outside of a Jakarta EE container.
+ *
* @since EL 3.0
*/
public class ELProcessor {
@@ -44,31 +48,82 @@ public class ELProcessor {
private final ELContext context = manager.getELContext();
private final ExpressionFactory factory = ELManager.getExpressionFactory();
+ /**
+ * Constructs an ELProcessor with a default {@link ELManager} and {@link StandardELContext}.
+ * The processor is ready to evaluate expressions immediately after construction.
+ */
+ public ELProcessor() {
+ }
+ /**
+ * Returns the {@link ELManager} that manages the EL context, resolvers, functions, and
+ * variables for this processor.
+ *
+ * @return the ELManager instance
+ */
public ELManager getELManager() {
return manager;
}
-
+ /**
+ * Evaluates the given EL expression and returns the result as the requested type.
+ * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
+ *
+ * @param <T> the expected result type
+ * @param expression the EL expression to evaluate
+ *
+ * @return the result of evaluating the expression, coerced to the requested type
+ *
+ * @throws ELException if the expression cannot be evaluated
+ */
public <T> T eval(String expression) {
@SuppressWarnings("unchecked")
T result = (T) getValue(expression, Object.class);
return result;
}
-
+ /**
+ * Evaluates the given EL expression and returns the result coerced to the expected type.
+ * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
+ *
+ * @param <T> the expected result type
+ * @param expression the EL expression to evaluate
+ * @param expectedType the class of the expected result type
+ *
+ * @return the result of evaluating the expression, coerced to the expected type
+ *
+ * @throws ELException if the expression cannot be evaluated
+ */
public <T> T getValue(String expression, Class<T> expectedType) {
ValueExpression ve = factory.createValueExpression(context, bracket(expression), expectedType);
return ve.getValue(context);
}
-
+ /**
+ * Evaluates the given EL expression and sets the result to the specified value.
+ * This is used for EL assignment expressions. The expression is automatically wrapped
+ * in {@literal ${}} delimiters before evaluation.
+ *
+ * @param expression the EL expression to evaluate
+ * @param value the value to assign
+ *
+ * @throws ELException if the expression cannot be evaluated or the target is not writable
+ */
public void setValue(String expression, Object value) {
ValueExpression ve = factory.createValueExpression(context, bracket(expression), Object.class);
ve.setValue(context, value);
}
-
+ /**
+ * Registers a variable in the EL context. The variable is associated with the result
+ * of evaluating the given expression. Passing a {@code null} expression removes the
+ * variable from the context.
+ *
+ * @param variable the variable name
+ * @param expression the EL expression to associate with the variable, or {@code null} to remove
+ *
+ * @throws ELException if the expression cannot be evaluated
+ */
public void setVariable(String variable, String expression) {
if (expression == null) {
manager.setVariable(variable, null);
@@ -78,7 +133,20 @@ public class ELProcessor {
}
}
-
+ /**
+ * Registers a function in the EL context by looking up the static method in the given class.
+ * The method name may include a return type and parameter signature in the format
+ * {@code returnType methodName(paramTypes)}. The function is then callable in EL expressions
+ * as {@code prefix:function(args)}.
+ *
+ * @param prefix the namespace prefix for the function
+ * @param function the local function name, or empty to use the method name
+ * @param className the fully qualified name of the class containing the static method
+ * @param methodName the method name, optionally with return type and parameter signature
+ *
+ * @throws ClassNotFoundException if the class cannot be found or is not public
+ * @throws NoSuchMethodException if the method cannot be found or is not a public static method
+ */
public void defineFunction(String prefix, String function, String className, String methodName)
throws ClassNotFoundException, NoSuchMethodException {
@@ -188,6 +256,14 @@ public class ELProcessor {
}
+ /**
+ * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
+ * is provided, it is stored under the given name. When {@code null} is provided, the
+ * bean with the given name is removed.
+ *
+ * @param name the bean name
+ * @param bean the bean object to define, or {@code null} to remove the bean
+ */
public void defineBean(String name, Object bean) {
manager.defineBean(name, bean);
}
diff --git a/java/jakarta/el/ELResolver.java b/java/jakarta/el/ELResolver.java
index e7dad5afcd..deaef98f2a 100644
--- a/java/jakarta/el/ELResolver.java
+++ b/java/jakarta/el/ELResolver.java
@@ -16,8 +16,25 @@
*/
package jakarta.el;
+/**
+ * Base class for resolvers that resolve property references during EL expression evaluation.
+ * An ELResolver is responsible for resolving a property on a base object, determining its type,
+ * setting its value, and reporting whether it is read-only. Resolvers are chained together in
+ * an {@link ELContext}, and each resolver in the chain attempts to resolve the property until
+ * one succeeds. Implementations include {@link ListELResolver}, {@link MapELResolver}, and
+ * custom resolvers for application-specific object models.
+ *
+ * @since EL 2.1
+ */
public abstract class ELResolver {
+ /**
+ * Constructs an ELResolver. Subclasses should invoke this constructor to initialize
+ * the base resolver state.
+ */
+ public ELResolver() {
+ }
+
/**
* Obtain the value of the given property on the given object using the given context.
*
diff --git a/java/jakarta/el/EvaluationListener.java b/java/jakarta/el/EvaluationListener.java
index 68c30985e0..836fac9e75 100644
--- a/java/jakarta/el/EvaluationListener.java
+++ b/java/jakarta/el/EvaluationListener.java
@@ -17,10 +17,20 @@
package jakarta.el;
/**
+ * Listener interface for monitoring EL expression evaluation events. Implementations can track when expressions are
+ * evaluated and when properties are resolved during evaluation. Register an instance with an {@link ELContext} using
+ * {@link ELContext#addEvaluationListener(EvaluationListener)}.
+ *
* @since EL 3.0
*/
public abstract class EvaluationListener {
+ /**
+ * Constructs an EvaluationListener.
+ */
+ public EvaluationListener() {
+ }
+
/**
* Fired before the evaluation of the expression.
*
diff --git a/java/jakarta/el/Expression.java b/java/jakarta/el/Expression.java
index 9c833768d4..b241e37415 100644
--- a/java/jakarta/el/Expression.java
+++ b/java/jakarta/el/Expression.java
@@ -20,13 +20,26 @@ import java.io.Serial;
import java.io.Serializable;
/**
- *
+ * Base class for EL expression objects. An Expression represents a compiled EL expression that can be evaluated.
+ * Subclasses include {@link ValueExpression} and {@link MethodExpression}.
*/
public abstract class Expression implements Serializable {
@Serial
private static final long serialVersionUID = -6663767980471823812L;
+ /**
+ * Constructs an Expression. Subclasses should invoke this constructor to initialize
+ * the base expression state.
+ */
+ public Expression() {
+ }
+
+ /**
+ * Returns the original string representation of this EL expression as it was parsed.
+ *
+ * @return the string representation of this expression
+ */
public abstract String getExpressionString();
@Override
@@ -35,6 +48,12 @@ public abstract class Expression implements Serializable {
@Override
public abstract int hashCode();
+ /**
+ * Returns whether this expression is a literal text expression, meaning it does not
+ * contain any variables, functions, or operators and evaluates to a constant value.
+ *
+ * @return {@code true} if this expression is a literal text, {@code false} otherwise
+ */
public abstract boolean isLiteralText();
}
diff --git a/java/jakarta/el/ExpressionFactory.java b/java/jakarta/el/ExpressionFactory.java
index bda510cea1..e327f7338b 100644
--- a/java/jakarta/el/ExpressionFactory.java
+++ b/java/jakarta/el/ExpressionFactory.java
@@ -35,10 +35,21 @@ import java.util.concurrent.locks.ReadWriteLock;
import java.util.concurrent.locks.ReentrantReadWriteLock;
/**
- * @since 2.1
+ * Factory for creating {@link ValueExpression} and {@link MethodExpression} instances, and for coercing objects to
+ * specific types. Implementations parse and compile EL expressions. Use {@link #newInstance()} to obtain an instance
+ * using the standard discovery mechanism.
+ *
+ * @since EL 2.1
*/
public abstract class ExpressionFactory {
+ /**
+ * Constructs an ExpressionFactory. Subclasses should invoke this constructor to initialize
+ * the base factory state.
+ */
+ public ExpressionFactory() {
+ }
+
private static final String PROPERTY_NAME = "jakarta.el.ExpressionFactory";
private static final String PROPERTY_FILE =
@@ -170,6 +181,16 @@ public abstract class ExpressionFactory {
*/
public abstract ValueExpression createValueExpression(ELContext context, String expression, Class<?> expectedType);
+ /**
+ * Creates a {@link ValueExpression} that, when evaluated, returns the given instance
+ * of the specified type. This is a convenience method for creating a constant value
+ * expression without requiring an {@link ELContext}.
+ *
+ * @param instance the constant value to wrap
+ * @param expectedType the expected type of the value
+ *
+ * @return a ValueExpression that returns the given instance when evaluated
+ */
public abstract ValueExpression createValueExpression(Object instance, Class<?> expectedType);
/**
@@ -202,7 +223,11 @@ public abstract class ExpressionFactory {
public abstract <T> T coerceToType(Object obj, Class<T> expectedType);
/**
- * @return This default implementation returns null
+ * Returns an {@link ELResolver} capable of resolving properties on {@link java.io.InputStream}
+ * objects, enabling EL expressions to operate on stream types. This allows expressions to
+ * read data from input streams using standard property navigation syntax.
+ *
+ * @return the StreamELResolver, or {@code null} if not supported by this implementation
*
* @since EL 3.0
*/
@@ -211,7 +236,11 @@ public abstract class ExpressionFactory {
}
/**
- * @return This default implementation returns null
+ * Returns a map of function names to {@link java.lang.reflect.Method} objects representing
+ * the standard EL functions that are available by default without explicit registration.
+ * Implementations can override this method to provide a set of built-in functions.
+ *
+ * @return a map of function names to methods, or {@code null} if no default functions are provided
*
* @since EL 3.0
*/
diff --git a/java/jakarta/el/FunctionMapper.java b/java/jakarta/el/FunctionMapper.java
index 036f12b7d2..fc3fc7c92a 100644
--- a/java/jakarta/el/FunctionMapper.java
+++ b/java/jakarta/el/FunctionMapper.java
@@ -18,8 +18,32 @@ package jakarta.el;
import java.lang.reflect.Method;
+/**
+ * Abstract base class for mapping EL function names to Java {@link java.lang.reflect.Method}
+ * objects. During expression evaluation, the EL implementation uses the FunctionMapper to
+ * resolve function references of the form {@code prefix:functionName} to the corresponding
+ * static Java methods. Implementations maintain a registry of function prefixes and names
+ * mapped to their underlying methods.
+ *
+ * @since EL 2.1
+ */
public abstract class FunctionMapper {
+ /**
+ * Constructs a FunctionMapper. Subclasses should invoke this constructor to initialize
+ * the base mapper state.
+ */
+ public FunctionMapper() {
+ }
+
+ /**
+ * Resolves a function reference to its corresponding static {@link java.lang.reflect.Method}.
+ *
+ * @param prefix the namespace prefix of the function
+ * @param localName the local name of the function
+ *
+ * @return the {@link Method} object for the resolved function, or {@code null} if not found
+ */
public abstract Method resolveFunction(String prefix, String localName);
/**
diff --git a/java/jakarta/el/ImportHandler.java b/java/jakarta/el/ImportHandler.java
index 2b0725b71e..5885f25730 100644
--- a/java/jakarta/el/ImportHandler.java
+++ b/java/jakarta/el/ImportHandler.java
@@ -28,6 +28,10 @@ import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
/**
+ * Manages class and package imports for EL expressions, similar to Java import statements. The ImportHandler resolves
+ * unqualified class names to their fully qualified counterparts, supports static imports, and maintains a set of
+ * standard packages that are automatically available in EL expressions.
+ *
* @since EL 3.0
*/
public class ImportHandler {
@@ -289,11 +293,24 @@ public class ImportHandler {
private final Map<String,Class<?>> statics = new ConcurrentHashMap<>();
+ /**
+ * Constructs an ImportHandler with the {@code java.lang} package pre-imported.
+ * The {@code java.lang} package is automatically available in all EL expressions.
+ */
public ImportHandler() {
importPackage("java.lang");
}
-
+ /**
+ * Imports a static field or method so it can be referenced by its simple name in EL
+ * expressions. The argument must be a fully qualified name in the form
+ * {@code className.staticMemberName}. The static member must be public.
+ *
+ * @param name the fully qualified name of the static member to import
+ *
+ * @throws ELException if the name is invalid, the class cannot be found, the static
+ * member does not exist, or the import would be ambiguous
+ */
public void importStatic(String name) throws ELException {
int lastPeriod = name.lastIndexOf('.');
@@ -349,6 +366,15 @@ public class ImportHandler {
}
+ /**
+ * Imports a class so it can be referenced by its simple name in EL expressions.
+ * The argument must be a fully qualified class name. If the simple name conflicts
+ * with a previously imported class, an exception is thrown.
+ *
+ * @param name the fully qualified class name to import
+ *
+ * @throws ELException if the class name is invalid or conflicts with an existing import
+ */
public void importClass(String name) throws ELException {
int lastPeriodIndex = name.lastIndexOf('.');
@@ -366,6 +392,14 @@ public class ImportHandler {
}
+ /**
+ * Imports all classes from a package so they can be referenced by their simple names
+ * in EL expressions. Classes from the imported package are resolved during expression
+ * evaluation. If a simple name is ambiguous across multiple imported packages, an
+ * {@link ELException} is thrown at resolution time.
+ *
+ * @param name the package name to import
+ */
public void importPackage(String name) {
// Import ambiguity is handled at resolution, not at import
// Whether the package exists is not checked,
@@ -377,6 +411,18 @@ public class ImportHandler {
}
+ /**
+ * Resolves an unqualified class name to a {@link Class} object by searching the
+ * registered class imports and package imports. The name must not contain a dot.
+ * Results are cached for performance. If the name is ambiguous across multiple
+ * packages, an {@link ELException} is thrown.
+ *
+ * @param name the unqualified class name to resolve
+ *
+ * @return the resolved {@link Class}, or {@code null} if the class cannot be found
+ *
+ * @throws ELException if the class name is ambiguous across imported packages
+ */
public Class<?> resolveClass(String name) {
if (name == null || name.contains(".")) {
return null;
@@ -445,6 +491,15 @@ public class ImportHandler {
}
+ /**
+ * Resolves a statically imported member name to the {@link Class} that declares it.
+ * The name is the simple name of the static field or method as registered by
+ * {@link #importStatic(String)}.
+ *
+ * @param name the simple name of the static member
+ *
+ * @return the declaring {@link Class}, or {@code null} if not found
+ */
public Class<?> resolveStatic(String name) {
return statics.get(name);
}
diff --git a/java/jakarta/el/LambdaExpression.java b/java/jakarta/el/LambdaExpression.java
index fe7d9ca233..757a47cf24 100644
--- a/java/jakarta/el/LambdaExpression.java
+++ b/java/jakarta/el/LambdaExpression.java
@@ -21,6 +21,14 @@ import java.util.List;
import java.util.Map;
import java.util.Objects;
+/**
+ * Represents a lambda expression in EL. A lambda expression has a list of formal parameters
+ * and a body expression. When invoked, the lambda binds the actual arguments to its formal
+ * parameters and evaluates the body expression within a scoped {@link ELContext}. Lambda
+ * expressions support nesting, with inner lambdas having access to outer lambda arguments.
+ *
+ * @since EL 3.0
+ */
public class LambdaExpression {
private final List<String> formalParameters;
@@ -28,16 +36,42 @@ public class LambdaExpression {
private final Map<String,Object> nestedArguments = new HashMap<>();
private ELContext context = null;
+ /**
+ * Constructs a LambdaExpression with the given formal parameters and body expression.
+ *
+ * @param formalParameters the list of formal parameter names for the lambda
+ * @param expression the body expression to evaluate when the lambda is invoked
+ */
public LambdaExpression(List<String> formalParameters, ValueExpression expression) {
this.formalParameters = formalParameters;
this.expression = expression;
}
+ /**
+ * Sets the {@link ELContext} to be used when this lambda is invoked without an explicit
+ * context argument. This is called automatically when the lambda is coerced to a
+ * functional interface type.
+ *
+ * @param context the ELContext to use for evaluation
+ */
public void setELContext(ELContext context) {
this.context = context;
}
+ /**
+ * Invokes the lambda expression with the given arguments in the specified EL context.
+ * The formal parameters are bound to the corresponding arguments, and the body
+ * expression is evaluated within a lambda scope. If the result is another lambda,
+ * the current arguments are made available to the nested lambda.
+ *
+ * @param context the ELContext in which to evaluate the lambda
+ * @param args the actual arguments to bind to the formal parameters
+ *
+ * @return the result of evaluating the lambda body expression
+ *
+ * @throws ELException if the number of arguments is less than the number of formal parameters
+ */
@SuppressWarnings("null") // args[i] can't be null due to earlier checks
public Object invoke(ELContext context, Object... args) throws ELException {
@@ -81,6 +115,17 @@ public class LambdaExpression {
}
}
+ /**
+ * Invokes the lambda expression with the given arguments using the EL context set by
+ * {@link #setELContext(ELContext)}. This is a convenience method for use when the
+ * lambda has been assigned to a functional interface variable.
+ *
+ * @param args the actual arguments to bind to the formal parameters
+ *
+ * @return the result of evaluating the lambda body expression
+ *
+ * @throws ELException if the number of arguments is less than the number of formal parameters
+ */
public Object invoke(Object... args) {
return invoke(context, args);
}
diff --git a/java/jakarta/el/ListELResolver.java b/java/jakarta/el/ListELResolver.java
index 13c73e16f6..34b0b15267 100644
--- a/java/jakarta/el/ListELResolver.java
+++ b/java/jakarta/el/ListELResolver.java
@@ -21,6 +21,14 @@ import java.util.Collections;
import java.util.List;
import java.util.Objects;
+/**
+ * An {@link ELResolver} that resolves properties on {@link java.util.List} objects using
+ * integer indices. When the base object is a {@code List}, the property is coerced to an
+ * integer and used as the list index. This resolver supports read and write operations,
+ * and can be configured as read-only to prevent modification of list elements.
+ *
+ * @since EL 2.1
+ */
public class ListELResolver extends ELResolver {
private final boolean readOnly;
@@ -29,10 +37,20 @@ public class ListELResolver extends ELResolver {
// classes. Java 9 + so a back-port would require JreCompat.
private static final Class<?> UNMODIFIABLE = Collections.unmodifiableList(new ArrayList<>()).getClass();
+ /**
+ * Constructs a ListELResolver that allows both read and write operations on lists.
+ */
public ListELResolver() {
this.readOnly = false;
}
+ /**
+ * Constructs a ListELResolver with the specified read-only setting. When read-only
+ * is {@code true}, attempts to set values on list elements will throw a
+ * {@link PropertyNotWritableException}.
+ *
+ * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
+ */
public ListELResolver(boolean readOnly) {
this.readOnly = readOnly;
}
diff --git a/java/jakarta/el/MapELResolver.java b/java/jakarta/el/MapELResolver.java
index 973d2ee35d..32272a8916 100644
--- a/java/jakarta/el/MapELResolver.java
+++ b/java/jakarta/el/MapELResolver.java
@@ -21,16 +21,34 @@ import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
+/**
+ * An {@link ELResolver} that resolves properties on {@link java.util.Map} objects using
+ * the property as a map key. When the base object is a {@code Map}, the property is used
+ * directly as the key to look up or set values. This resolver supports read and write
+ * operations, and can be configured as read-only to prevent modification of map entries.
+ *
+ * @since EL 2.1
+ */
public class MapELResolver extends ELResolver {
private static final Class<?> UNMODIFIABLE = Collections.unmodifiableMap(new HashMap<>()).getClass();
private final boolean readOnly;
+ /**
+ * Constructs a MapELResolver that allows both read and write operations on maps.
+ */
public MapELResolver() {
this.readOnly = false;
}
+ /**
+ * Constructs a MapELResolver with the specified read-only setting. When read-only
+ * is {@code true}, attempts to set values on map entries will throw a
+ * {@link PropertyNotWritableException}.
+ *
+ * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
+ */
public MapELResolver(boolean readOnly) {
this.readOnly = readOnly;
}
diff --git a/java/jakarta/el/MethodExpression.java b/java/jakarta/el/MethodExpression.java
index 715cf43bb9..876619b07f 100644
--- a/java/jakarta/el/MethodExpression.java
+++ b/java/jakarta/el/MethodExpression.java
@@ -18,12 +18,24 @@ package jakarta.el;
import java.io.Serial;
+/**
+ * Represents a compiled EL method expression. A MethodExpression is the result of compiling an EL expression
+ * that resolves to a method, and can be invoked at a later time with a given set of parameters.
+ */
public abstract class MethodExpression extends Expression {
@Serial
private static final long serialVersionUID = 8163925562047324656L;
/**
+ * Constructs a MethodExpression.
+ */
+ public MethodExpression() {
+ }
+
+ /**
+ * Returns information about the method that this expression resolves to.
+ *
* @param context The EL context for this evaluation
*
* @return Information about the method that this expression resolves to
@@ -37,6 +49,8 @@ public abstract class MethodExpression extends Expression {
public abstract MethodInfo getMethodInfo(ELContext context);
/**
+ * Invokes the method that this expression resolves to with the given parameters.
+ *
* @param context The EL context for this evaluation
* @param params The parameters with which to invoke this method expression
*
@@ -52,6 +66,8 @@ public abstract class MethodExpression extends Expression {
public abstract Object invoke(ELContext context, Object[] params);
/**
+ * Returns whether the parameters for the method invocation are provided by the expression or by the container.
+ *
* @return This default implementation always returns <code>false</code>
*
* @since EL 3.0
diff --git a/java/jakarta/el/MethodInfo.java b/java/jakarta/el/MethodInfo.java
index 3dbcfe75a1..034433d303 100644
--- a/java/jakarta/el/MethodInfo.java
+++ b/java/jakarta/el/MethodInfo.java
@@ -18,28 +18,57 @@ package jakarta.el;
import java.util.Arrays;
+/**
+ * Holds metadata about a method that an EL method expression resolves to, including the method name,
+ * return type, and parameter types.
+ */
public class MethodInfo {
+ /** The name of the method. */
private final String name;
+ /** The parameter types of the method. */
private final Class<?>[] paramTypes;
+ /** The return type of the method. */
private final Class<?> returnType;
+ /**
+ * Constructs a MethodInfo with the given name, return type, and parameter types.
+ *
+ * @param name The name of the method
+ * @param returnType The return type of the method
+ * @param paramTypes The parameter types of the method
+ */
public MethodInfo(String name, Class<?> returnType, Class<?>[] paramTypes) {
this.name = name;
this.returnType = returnType;
this.paramTypes = paramTypes;
}
+ /**
+ * Returns the name of the method.
+ *
+ * @return the method name
+ */
public String getName() {
return this.name;
}
+ /**
+ * Returns the return type of the method.
+ *
+ * @return the return type
+ */
public Class<?> getReturnType() {
return this.returnType;
}
+ /**
+ * Returns the parameter types of the method.
+ *
+ * @return the parameter types
+ */
public Class<?>[] getParamTypes() {
return this.paramTypes;
}
diff --git a/java/jakarta/el/MethodNotFoundException.java b/java/jakarta/el/MethodNotFoundException.java
index 8a92baf0f3..7232656c97 100644
--- a/java/jakarta/el/MethodNotFoundException.java
+++ b/java/jakarta/el/MethodNotFoundException.java
@@ -18,23 +18,45 @@ package jakarta.el;
import java.io.Serial;
+/**
+ * Thrown when a method referenced in an EL expression cannot be found on the target object.
+ */
public class MethodNotFoundException extends ELException {
@Serial
private static final long serialVersionUID = -3631968116081480328L;
+ /**
+ * Constructs a MethodNotFoundException with no detail message.
+ */
public MethodNotFoundException() {
super();
}
+ /**
+ * Constructs a MethodNotFoundException with the specified detail message.
+ *
+ * @param message the detail message
+ */
public MethodNotFoundException(String message) {
super(message);
}
+ /**
+ * Constructs a MethodNotFoundException with the specified cause.
+ *
+ * @param cause the cause of this exception
+ */
public MethodNotFoundException(Throwable cause) {
super(cause);
}
+ /**
+ * Constructs a MethodNotFoundException with the specified detail message and cause.
+ *
+ * @param message the detail message
+ * @param cause the cause of this exception
+ */
public MethodNotFoundException(String message, Throwable cause) {
super(message, cause);
}
diff --git a/java/jakarta/el/MethodReference.java b/java/jakarta/el/MethodReference.java
index 6f86ffcbea..86b008faac 100644
--- a/java/jakarta/el/MethodReference.java
+++ b/java/jakarta/el/MethodReference.java
@@ -26,12 +26,24 @@ import java.util.Arrays;
*/
public class MethodReference {
+ /** The base object on which the method will be invoked. */
private final Object base;
+ /** The method information. */
private final MethodInfo methodInfo;
+ /** The annotations on the method. */
private final Annotation[] annotations;
+ /** The evaluated parameter values for the method invocation. */
private final Object[] evaluatedParameters;
+ /**
+ * Constructs a MethodReference with the given base object, method info, annotations, and evaluated parameters.
+ *
+ * @param base The base object on which the method will be invoked
+ * @param methodInfo Information about the method
+ * @param annotations The annotations on the method
+ * @param evaluatedParameters The evaluated parameter values for the method invocation
+ */
public MethodReference(Object base, MethodInfo methodInfo, Annotation[] annotations, Object[] evaluatedParameters) {
this.base = base;
this.methodInfo = methodInfo;
diff --git a/java/jakarta/el/OptionalELResolver.java b/java/jakarta/el/OptionalELResolver.java
index 9600e1abca..4b59e62d37 100644
--- a/java/jakarta/el/OptionalELResolver.java
+++ b/java/jakarta/el/OptionalELResolver.java
@@ -30,6 +30,12 @@ import java.util.Optional;
*/
public class OptionalELResolver extends ELResolver {
+ /**
+ * Constructs an OptionalELResolver.
+ */
+ public OptionalELResolver() {
+ }
+
/**
* {@inheritDoc}
*
diff --git a/java/jakarta/el/PropertyNotFoundException.java b/java/jakarta/el/PropertyNotFoundException.java
index 45aff2e48b..7f8aa90598 100644
--- a/java/jakarta/el/PropertyNotFoundException.java
+++ b/java/jakarta/el/PropertyNotFoundException.java
@@ -18,23 +18,50 @@ package jakarta.el;
import java.io.Serial;
+/**
+ * Exception thrown when a property is not found during EL evaluation.
+ * <p>
+ * This exception is raised when an expression attempts to access a property
+ * that does not exist on the target object.
+ *
+ * @since EL 2.1
+ */
public class PropertyNotFoundException extends ELException {
@Serial
private static final long serialVersionUID = -3799200961303506745L;
+ /**
+ * Constructs a new instance with no detail message or cause.
+ */
public PropertyNotFoundException() {
super();
}
+ /**
+ * Constructs a new instance with the specified detail message and no cause.
+ *
+ * @param message the detail message
+ */
public PropertyNotFoundException(String message) {
super(message);
}
+ /**
+ * Constructs a new instance with the specified cause and no detail message.
+ *
+ * @param cause the underlying cause
+ */
public PropertyNotFoundException(Throwable cause) {
super(cause);
}
+ /**
+ * Constructs a new instance with the specified detail message and cause.
+ *
+ * @param message the detail message
+ * @param cause the underlying cause
+ */
public PropertyNotFoundException(String message, Throwable cause) {
super(message, cause);
}
diff --git a/java/jakarta/el/PropertyNotWritableException.java b/java/jakarta/el/PropertyNotWritableException.java
index 58f28e9c34..14b53ba4ca 100644
--- a/java/jakarta/el/PropertyNotWritableException.java
+++ b/java/jakarta/el/PropertyNotWritableException.java
@@ -18,23 +18,50 @@ package jakarta.el;
import java.io.Serial;
+/**
+ * Exception thrown when an EL expression attempts to write to a read-only property.
+ * <p>
+ * This exception is raised during setValue operations when the target property
+ * exists but cannot be modified.
+ *
+ * @since EL 2.1
+ */
public class PropertyNotWritableException extends ELException {
@Serial
private static final long serialVersionUID = 827987155471214717L;
+ /**
+ * Constructs a new instance with no detail message or cause.
+ */
public PropertyNotWritableException() {
super();
}
+ /**
+ * Constructs a new instance with the specified detail message and no cause.
+ *
+ * @param message the detail message
+ */
public PropertyNotWritableException(String message) {
super(message);
}
+ /**
+ * Constructs a new instance with the specified cause and no detail message.
+ *
+ * @param cause the underlying cause
+ */
public PropertyNotWritableException(Throwable cause) {
super(cause);
}
+ /**
+ * Constructs a new instance with the specified detail message and cause.
+ *
+ * @param message the detail message
+ * @param cause the underlying cause
+ */
public PropertyNotWritableException(String message, Throwable cause) {
super(message, cause);
}
diff --git a/java/jakarta/el/RecordELResolver.java b/java/jakarta/el/RecordELResolver.java
index 37c0cc64a3..01b4dc6792 100644
--- a/java/jakarta/el/RecordELResolver.java
+++ b/java/jakarta/el/RecordELResolver.java
@@ -35,6 +35,13 @@ import java.util.Objects;
*/
public class RecordELResolver extends ELResolver {
+ /**
+ * Constructs a new instance of the resolver.
+ */
+ public RecordELResolver() {
+ super();
+ }
+
/**
* If the base object is an instance of {@link Record}, returns the value of the given field of this {@link Record}.
* <p>
diff --git a/java/jakarta/el/ResourceBundleELResolver.java b/java/jakarta/el/ResourceBundleELResolver.java
index 62e9fd6729..2ae2ae054e 100644
--- a/java/jakarta/el/ResourceBundleELResolver.java
+++ b/java/jakarta/el/ResourceBundleELResolver.java
@@ -20,8 +20,26 @@ import java.util.MissingResourceException;
import java.util.Objects;
import java.util.ResourceBundle;
+/**
+ * EL resolver for resource bundle properties.
+ * <p>
+ * This resolver handles base objects of type {@link ResourceBundle}. It accepts
+ * any non-null object as a property, coerces it to a String, and uses it to
+ * look up the corresponding message in the resource bundle. If the key is not
+ * found, the resolver returns a placeholder string of the form {@code ???key???}.
+ * Resource bundles are always read-only.
+ * <p>
+ * {@code ELResolver}s are combined using {@link CompositeELResolver}s to define
+ * rich semantics for evaluating an expression. See the javadocs for
+ * {@link ELResolver} for details.
+ *
+ * @since EL 2.1
+ */
public class ResourceBundleELResolver extends ELResolver {
+ /**
+ * Constructs a new instance of the resolver.
+ */
public ResourceBundleELResolver() {
super();
}
diff --git a/java/jakarta/el/StandardELContext.java b/java/jakarta/el/StandardELContext.java
index 17c5f44b3d..ce2ed86605 100644
--- a/java/jakarta/el/StandardELContext.java
+++ b/java/jakarta/el/StandardELContext.java
@@ -21,6 +21,10 @@ import java.util.HashMap;
import java.util.Map;
/**
+ * Standard implementation of {@link ELContext} that provides a complete EL resolution environment. It maintains a
+ * composite resolver chain, variable mapper, function mapper, and supports custom resolvers and local beans. This is
+ * the default context implementation used by {@link ELProcessor}.
+ *
* @since EL 3.0
*/
public class StandardELContext extends ELContext {
@@ -33,6 +37,14 @@ public class StandardELContext extends ELContext {
private final Map<String,Object> localBeans = new HashMap<>();
+ /**
+ * Constructs a new instance backed by the given expression factory.
+ * <p>
+ * Initializes the standard resolver chain with built-in resolvers and
+ * a function mapper populated from the factory's initial function map.
+ *
+ * @param factory the expression factory providing the initial resolver and function configuration
+ */
public StandardELContext(ExpressionFactory factory) {
wrappedContext = null;
variableMapper = new StandardVariableMapper();
@@ -57,6 +69,14 @@ public class StandardELContext extends ELContext {
standardResolver.add(new BeanELResolver());
}
+ /**
+ * Constructs a new instance that wraps the given context.
+ * <p>
+ * The variable mapper, function mapper, and EL resolver from the wrapped
+ * context are used, with additional standard resolvers prepended.
+ *
+ * @param context the context to wrap
+ */
public StandardELContext(ELContext context) {
wrappedContext = context;
variableMapper = context.getVariableMapper();
@@ -94,6 +114,15 @@ public class StandardELContext extends ELContext {
return standardResolver;
}
+ /**
+ * Adds a custom EL resolver to the resolver chain.
+ * <p>
+ * Custom resolvers are inserted after the bean name resolver and before
+ * the standard resolvers, allowing them to intercept resolution before
+ * the built-in resolvers are consulted.
+ *
+ * @param resolver the resolver to add
+ */
public void addELResolver(ELResolver resolver) {
customResolvers.add(resolver);
}
diff --git a/java/jakarta/el/StaticFieldELResolver.java b/java/jakarta/el/StaticFieldELResolver.java
index c69e306005..d77e0c733a 100644
--- a/java/jakarta/el/StaticFieldELResolver.java
+++ b/java/jakarta/el/StaticFieldELResolver.java
@@ -24,10 +24,21 @@ import java.lang.reflect.Modifier;
import java.util.Objects;
/**
+ * ELResolver that resolves static fields and invokes static methods on classes. This resolver handles expressions
+ * where the base is an {@link ELClass} and the property is a {@link String} representing a field or method name.
+ * Static fields are read-only.
+ *
* @since EL 3.0
*/
public class StaticFieldELResolver extends ELResolver {
+ /**
+ * Constructs a new instance of the resolver.
+ */
+ public StaticFieldELResolver() {
+ super();
+ }
+
@Override
public Object getValue(ELContext context, Object base, Object property) {
Objects.requireNonNull(context);
diff --git a/java/jakarta/el/TypeConverter.java b/java/jakarta/el/TypeConverter.java
index 532543d3da..acc2acf370 100644
--- a/java/jakarta/el/TypeConverter.java
+++ b/java/jakarta/el/TypeConverter.java
@@ -17,10 +17,21 @@
package jakarta.el;
/**
+ * Base class for ELResolvers that perform type conversion. A TypeConverter is an ELResolver that specializes in
+ * converting objects from one type to another via the {@link #convertToType} method. Standard property resolution
+ * methods return {@code null} or no-op, as this resolver is focused solely on type conversion.
+ *
* @since EL 3.0
*/
public abstract class TypeConverter extends ELResolver {
+ /**
+ * Constructs a new instance of the type converter.
+ */
+ public TypeConverter() {
+ super();
+ }
+
@Override
public Object getValue(ELContext context, Object base, Object property) {
return null;
diff --git a/java/jakarta/el/ValueExpression.java b/java/jakarta/el/ValueExpression.java
index 892c96128c..2db42cdbca 100644
--- a/java/jakarta/el/ValueExpression.java
+++ b/java/jakarta/el/ValueExpression.java
@@ -18,12 +18,29 @@ package jakarta.el;
import java.io.Serial;
+/**
+ * Represents a parsed EL expression that can be evaluated to produce a value.
+ * <p>
+ * A value expression is created by parsing an EL expression string and can be
+ * evaluated multiple times in different contexts. It supports reading values,
+ * writing values, and introspecting the expression's type and mutability.
+ *
+ * @since EL 2.1
+ */
public abstract class ValueExpression extends Expression {
@Serial
private static final long serialVersionUID = 8577809572381654673L;
/**
+ * Constructs a new value expression.
+ */
+ public ValueExpression() {
+ }
+
+ /**
+ * Evaluates this expression and returns the result.
+ *
* @param <T> The expected type for the result of evaluating this value expression
* @param context The EL context for this evaluation
*
@@ -37,6 +54,8 @@ public abstract class ValueExpression extends Expression {
public abstract <T> T getValue(ELContext context);
/**
+ * Sets the value of the property referenced by this expression.
+ *
* @param context The EL context for this evaluation
* @param value The value to set the property to which this value expression refers
*
@@ -49,6 +68,8 @@ public abstract class ValueExpression extends Expression {
public abstract void setValue(ELContext context, Object value);
/**
+ * Determines whether the property referenced by this expression is read-only.
+ *
* @param context The EL context for this evaluation
*
* @return <code>true</code> if this expression is read only otherwise <code>false</code>
@@ -61,6 +82,8 @@ public abstract class ValueExpression extends Expression {
public abstract boolean isReadOnly(ELContext context);
/**
+ * Returns the type of the result produced by evaluating this expression.
+ *
* @param context The EL context for this evaluation
*
* @return The type of the result of this value expression
@@ -72,9 +95,19 @@ public abstract class ValueExpression extends Expression {
*/
public abstract Class<?> getType(ELContext context);
+ /**
+ * Returns the expected type of the result of this expression.
+ *
+ * @return The expected result type, or {@code Object.class} if no specific type is expected
+ */
public abstract Class<?> getExpectedType();
/**
+ * Returns a reference to the resolved property for this expression.
+ * <p>
+ * This default implementation always returns {@code null}. Subclasses should
+ * override this method to provide the resolved base object and property.
+ *
* @param context The EL context for this evaluation
*
* @return This default implementation always returns <code>null</code>
diff --git a/java/jakarta/el/ValueReference.java b/java/jakarta/el/ValueReference.java
index b7b2cee9ed..53090d7288 100644
--- a/java/jakarta/el/ValueReference.java
+++ b/java/jakarta/el/ValueReference.java
@@ -20,6 +20,10 @@ import java.io.Serial;
import java.io.Serializable;
/**
+ * Holds a reference to a resolved property, consisting of a base object and a property identifier. This class is
+ * used to capture the result of property resolution during EL evaluation, allowing the caller to perform additional
+ * operations on the resolved property.
+ *
* @since EL 2.2
*/
public class ValueReference implements Serializable {
@@ -27,18 +31,37 @@ public class ValueReference implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
+ /** The base object on which the property was resolved. */
private final Object base;
+
+ /** The property identifier. */
private final Object property;
+ /**
+ * Constructs a new value reference with the given base object and property.
+ *
+ * @param base The base object on which the property was resolved
+ * @param property The property identifier
+ */
public ValueReference(Object base, Object property) {
this.base = base;
this.property = property;
}
+ /**
+ * Returns the base object on which the property was resolved.
+ *
+ * @return The base object
+ */
public Object getBase() {
return base;
}
+ /**
+ * Returns the property identifier.
+ *
+ * @return The property identifier
+ */
public Object getProperty() {
return property;
}
diff --git a/java/jakarta/el/VariableMapper.java b/java/jakarta/el/VariableMapper.java
index 79018e0f0d..8d41c6b7e5 100644
--- a/java/jakarta/el/VariableMapper.java
+++ b/java/jakarta/el/VariableMapper.java
@@ -17,11 +17,34 @@
package jakarta.el;
/**
- *
+ * Manages the mapping between variable names and their corresponding {@link ValueExpression} instances within an
+ * {@link ELContext}. Variable mappings allow EL expressions to reference named variables that resolve to computed
+ * values.
*/
public abstract class VariableMapper {
+ /**
+ * Default constructor for subclasses.
+ */
+ public VariableMapper() {
+ }
+
+ /**
+ * Resolves a variable name to its corresponding ValueExpression.
+ *
+ * @param variable the name of the variable to resolve
+ *
+ * @return the ValueExpression for the variable, or {@code null} if not found
+ */
public abstract ValueExpression resolveVariable(String variable);
+ /**
+ * Sets or removes a variable mapping.
+ *
+ * @param variable the name of the variable
+ * @param expression the ValueExpression to associate with the variable, or {@code null} to remove the mapping
+ *
+ * @return the previous ValueExpression for the variable, or {@code null} if there was no mapping
+ */
public abstract ValueExpression setVariable(String variable, ValueExpression expression);
}
diff --git a/java/jakarta/mail/Authenticator.java b/java/jakarta/mail/Authenticator.java
index 65866750ef..3896516877 100644
--- a/java/jakarta/mail/Authenticator.java
+++ b/java/jakarta/mail/Authenticator.java
@@ -16,7 +16,25 @@
*/
package jakarta.mail;
+/**
+ * Abstract base class for providing user authentication when establishing network connections. Subclasses override
+ * {@link #getPasswordAuthentication} to return the appropriate credentials. This class is part of the Jakarta Mail
+ * API and follows the pattern defined by {@link java.net.Authenticator}.
+ */
public class Authenticator {
+
+ /**
+ * Default constructor for subclasses.
+ */
+ public Authenticator() {
+ }
+
+ /**
+ * Returns the password authentication information for the current request. The default implementation returns
+ * {@code null}. Subclasses should override this method to provide actual credentials.
+ *
+ * @return the PasswordAuthentication object, or {@code null} if no authentication is available
+ */
protected PasswordAuthentication getPasswordAuthentication() {
return null;
}
diff --git a/java/jakarta/mail/PasswordAuthentication.java b/java/jakarta/mail/PasswordAuthentication.java
index 7be7b29e85..a76f8b7909 100644
--- a/java/jakarta/mail/PasswordAuthentication.java
+++ b/java/jakarta/mail/PasswordAuthentication.java
@@ -16,8 +16,20 @@
*/
package jakarta.mail;
+/**
+ * Stores username and password credentials for mail authentication. This class follows the pattern defined by
+ * {@link java.net.PasswordAuthentication} and is used with {@link Authenticator} to provide credentials when
+ * establishing mail connections.
+ */
@SuppressWarnings("unused") // Dummy implementation
public class PasswordAuthentication {
+
+ /**
+ * Constructs a PasswordAuthentication with the given user and password.
+ *
+ * @param user the username
+ * @param password the password
+ */
public PasswordAuthentication(String user, String password) {
// Dummy implementation
}
diff --git a/java/jakarta/mail/Session.java b/java/jakarta/mail/Session.java
index 87ff869d3b..35f221afff 100644
--- a/java/jakarta/mail/Session.java
+++ b/java/jakarta/mail/Session.java
@@ -18,12 +18,34 @@ package jakarta.mail;
import java.util.Properties;
+/**
+ * Represents a mail session configuration.
+ */
@SuppressWarnings("unused") // Dummy implementation
public class Session {
+ /**
+ * Default constructor.
+ */
+ public Session() {
+ }
+
+ /**
+ * Returns a Session object with the given properties and authenticator.
+ *
+ * @param props the session properties
+ * @param auth the authenticator
+ * @return the mail session
+ */
public static Session getInstance(Properties props, Authenticator auth) {
return null;
}
+ /**
+ * Returns a Session object with the given properties.
+ *
+ * @param props the session properties
+ * @return the mail session
+ */
public static Session getInstance(Properties props) {
return null;
}
diff --git a/java/jakarta/mail/internet/InternetAddress.java b/java/jakarta/mail/internet/InternetAddress.java
index aa1ce3859e..5d766f5e4d 100644
--- a/java/jakarta/mail/internet/InternetAddress.java
+++ b/java/jakarta/mail/internet/InternetAddress.java
@@ -16,8 +16,19 @@
*/
package jakarta.mail.internet;
+/**
+ * Represents an Internet email address as defined by RFC 822.
+ * An Internet address consists of an optional personal name and
+ * an address string in the form of local-part@domain.
+ */
@SuppressWarnings("unused") // Dummy implementation
public class InternetAddress {
+ /**
+ * Constructs an InternetAddress from the specified address string.
+ * The address string may optionally include a personal name portion.
+ *
+ * @param from the email address string to parse
+ */
public InternetAddress(String from) {
// Dummy implementation
}
diff --git a/java/jakarta/mail/internet/MimeMessage.java b/java/jakarta/mail/internet/MimeMessage.java
index 39644f0509..3fae2b288c 100644
--- a/java/jakarta/mail/internet/MimeMessage.java
+++ b/java/jakarta/mail/internet/MimeMessage.java
@@ -18,16 +18,35 @@ package jakarta.mail.internet;
import jakarta.mail.Session;
+/**
+ * Represents a MIME message in the Jakarta Mail API.
+ * Provides methods for setting message headers such as sender and subject.
+ */
@SuppressWarnings("unused") // Dummy implementation
public class MimeMessage implements MimePart {
+ /**
+ * Constructs a MimeMessage with the given Session.
+ *
+ * @param session the mail session used to create this message
+ */
public MimeMessage(Session session) {
// Dummy implementation
}
+ /**
+ * Sets the InternetAddress of the message sender.
+ *
+ * @param from the InternetAddress of the sender
+ */
public void setFrom(InternetAddress from) {
// Dummy implementation
}
+ /**
+ * Sets the subject of the message.
+ *
+ * @param subject the subject string
+ */
public void setSubject(String subject) {
// Dummy implementation
}
diff --git a/java/jakarta/mail/internet/MimePart.java b/java/jakarta/mail/internet/MimePart.java
index 7591634fae..0be69d33e6 100644
--- a/java/jakarta/mail/internet/MimePart.java
+++ b/java/jakarta/mail/internet/MimePart.java
@@ -16,6 +16,10 @@
*/
package jakarta.mail.internet;
+/**
+ * Represents a part of a MIME message in the Jakarta Mail API.
+ * A MimePart can contain content and headers for a single MIME entity.
+ */
public interface MimePart {
// Dummy implementation
}
diff --git a/java/jakarta/mail/internet/MimePartDataSource.java b/java/jakarta/mail/internet/MimePartDataSource.java
index a86bae55ea..17b946b53a 100644
--- a/java/jakarta/mail/internet/MimePartDataSource.java
+++ b/java/jakarta/mail/internet/MimePartDataSource.java
@@ -16,8 +16,17 @@
*/
package jakarta.mail.internet;
+/**
+ * Provides a DataSource representation for a MimePart.
+ * Wraps a MimePart so it can be used where a DataSource is required.
+ */
@SuppressWarnings("unused") // Dummy implementation
public class MimePartDataSource {
+ /**
+ * Constructs a MimePartDataSource wrapping the given MimePart.
+ *
+ * @param part the MimePart to wrap
+ */
public MimePartDataSource(MimePart part) {
// Dummy implementation
}
diff --git a/java/jakarta/persistence/PersistenceContext.java b/java/jakarta/persistence/PersistenceContext.java
index 78ece9e615..c0963ab44c 100644
--- a/java/jakarta/persistence/PersistenceContext.java
+++ b/java/jakarta/persistence/PersistenceContext.java
@@ -21,17 +21,45 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Specifies the entity manager for use with an entity bean or other managed class.
+ * Used to inject a persistence context into a Jakarta EE managed component.
+ */
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
-
public @interface PersistenceContext {
+ /**
+ * The name used to look up the persistence context.
+ *
+ * @return the persistence context name
+ */
String name() default "";
+ /**
+ * The unit name of the persistence unit to associate with the persistence context.
+ *
+ * @return the persistence unit name
+ */
String unitName() default "";
+ /**
+ * The type of the persistence context.
+ *
+ * @return the persistence context type
+ */
PersistenceContextType type() default PersistenceContextType.TRANSACTION;
+ /**
+ * Properties used to configure the persistence context.
+ *
+ * @return the configuration properties
+ */
PersistenceProperty[] properties() default {};
+ /**
+ * The synchronization type of the persistence context with the transaction.
+ *
+ * @return the synchronization type
+ */
SynchronizationType synchronization() default SynchronizationType.SYNCHRONIZED;
}
diff --git a/java/jakarta/persistence/PersistenceContextType.java b/java/jakarta/persistence/PersistenceContextType.java
index 0e54e3c1ad..9f4af89442 100644
--- a/java/jakarta/persistence/PersistenceContextType.java
+++ b/java/jakarta/persistence/PersistenceContextType.java
@@ -16,7 +16,21 @@
*/
package jakarta.persistence;
+/**
+ * Defines the type of persistence context.
+ */
public enum PersistenceContextType {
+ /**
+ * The default persistence context type.
+ * The entity manager is tied to the current transaction and is automatically
+ * closed when the transaction completes.
+ */
TRANSACTION,
+
+ /**
+ * An extended persistence context type.
+ * The entity manager spans multiple transactions and remains open
+ * until explicitly closed by the application.
+ */
EXTENDED
-}
\ No newline at end of file
+}
diff --git a/java/jakarta/persistence/PersistenceContexts.java b/java/jakarta/persistence/PersistenceContexts.java
index 671d117c7c..ab3f2d49ce 100644
--- a/java/jakarta/persistence/PersistenceContexts.java
+++ b/java/jakarta/persistence/PersistenceContexts.java
@@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Groups multiple PersistenceContext annotations for injection into a single component.
+ */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-
public @interface PersistenceContexts {
+ /**
+ * The array of PersistenceContext annotations.
+ *
+ * @return the persistence contexts
+ */
PersistenceContext[] value();
}
diff --git a/java/jakarta/persistence/PersistenceProperty.java b/java/jakarta/persistence/PersistenceProperty.java
index 3ed05e1982..8c39f8a41b 100644
--- a/java/jakarta/persistence/PersistenceProperty.java
+++ b/java/jakarta/persistence/PersistenceProperty.java
@@ -20,11 +20,24 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Specifies a property for configuring a persistence context or persistence unit.
+ * Used within the properties element of PersistenceContext or PersistenceUnit annotations.
+ */
@Target({})
@Retention(RetentionPolicy.RUNTIME)
-
public @interface PersistenceProperty {
+ /**
+ * The name of the property.
+ *
+ * @return the property name
+ */
String name();
+ /**
+ * The value of the property.
+ *
+ * @return the property value
+ */
String value();
}
diff --git a/java/jakarta/persistence/PersistenceUnit.java b/java/jakarta/persistence/PersistenceUnit.java
index 0580f11112..5d72ed565a 100644
--- a/java/jakarta/persistence/PersistenceUnit.java
+++ b/java/jakarta/persistence/PersistenceUnit.java
@@ -21,11 +21,25 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Specifies a persistence unit for use with an entity bean or other managed class. Used to inject an
+ * EntityManagerFactory into a Jakarta EE managed component.
+ */
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
-
public @interface PersistenceUnit {
+
+ /**
+ * The name used to look up the EntityManagerFactory.
+ *
+ * @return the lookup name
+ */
String name() default "";
+ /**
+ * The unit name of the persistence unit.
+ *
+ * @return the persistence unit name
+ */
String unitName() default "";
}
diff --git a/java/jakarta/persistence/PersistenceUnits.java b/java/jakarta/persistence/PersistenceUnits.java
index 3da4da578e..d1260eb30a 100644
--- a/java/jakarta/persistence/PersistenceUnits.java
+++ b/java/jakarta/persistence/PersistenceUnits.java
@@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Groups multiple PersistenceUnit annotations for injection into a single component.
+ */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-
public @interface PersistenceUnits {
+ /**
+ * The array of PersistenceUnit annotations.
+ *
+ * @return the persistence units
+ */
PersistenceUnit[] value();
}
diff --git a/java/jakarta/persistence/SynchronizationType.java b/java/jakarta/persistence/SynchronizationType.java
index b1d5c1acc5..40ad6bf5ac 100644
--- a/java/jakarta/persistence/SynchronizationType.java
+++ b/java/jakarta/persistence/SynchronizationType.java
@@ -16,7 +16,16 @@
*/
package jakarta.persistence;
+/**
+ * Specifies the synchronization type of an entity manager with JTA transactions.
+ */
public enum SynchronizationType {
+ /**
+ * The entity manager participates in the current JTA transaction.
+ */
SYNCHRONIZED,
+ /**
+ * The entity manager does not participate in the current JTA transaction.
+ */
UNSYNCHRONIZED
}
diff --git a/java/jakarta/security/auth/message/AuthException.java b/java/jakarta/security/auth/message/AuthException.java
index f5a71e44fc..40cd5a47cd 100644
--- a/java/jakarta/security/auth/message/AuthException.java
+++ b/java/jakarta/security/auth/message/AuthException.java
@@ -20,13 +20,25 @@ import java.io.Serial;
import javax.security.auth.login.LoginException;
+/**
+ * Exception thrown when a JASPIC authentication operation fails. This exception is used by authentication modules
+ * and contexts to signal errors during the authentication process.
+ */
public class AuthException extends LoginException {
@Serial
private static final long serialVersionUID = -1156951780670243758L;
+ /**
+ * Constructs an AuthException with no detail message.
+ */
public AuthException() {
}
+ /**
+ * Constructs an AuthException with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public AuthException(String msg) {
super(msg);
}
diff --git a/java/jakarta/security/auth/message/AuthStatus.java b/java/jakarta/security/auth/message/AuthStatus.java
index ec009c80b4..c927296493 100644
--- a/java/jakarta/security/auth/message/AuthStatus.java
+++ b/java/jakarta/security/auth/message/AuthStatus.java
@@ -16,12 +16,35 @@
*/
package jakarta.security.auth.message;
+/**
+ * Represents the status returned by JASPIC authentication operations. The authentication status indicates whether
+ * authentication succeeded, failed, or requires further message exchange.
+ */
public class AuthStatus {
+ /**
+ * Authentication succeeded and no further message exchange is required.
+ */
public static final AuthStatus SUCCESS = new AuthStatus("SUCCESS");
+
+ /**
+ * Authentication failed and no further message exchange will change the outcome.
+ */
public static final AuthStatus FAILURE = new AuthStatus("FAILURE");
+
+ /**
+ * Authentication succeeded and the response should be sent to the peer.
+ */
public static final AuthStatus SEND_SUCCESS = new AuthStatus("SEND_SUCCESS");
+
+ /**
+ * Authentication failed and the failure response should be sent to the peer.
+ */
public static final AuthStatus SEND_FAILURE = new AuthStatus("SEND_FAILURE");
+
+ /**
+ * Authentication is in progress and further message exchange is required.
+ */
public static final AuthStatus SEND_CONTINUE = new AuthStatus("SEND_CONTINUE");
private final String name;
diff --git a/java/jakarta/security/auth/message/ClientAuth.java b/java/jakarta/security/auth/message/ClientAuth.java
index 79bda35aff..a4937e06fb 100644
--- a/java/jakarta/security/auth/message/ClientAuth.java
+++ b/java/jakarta/security/auth/message/ClientAuth.java
@@ -18,6 +18,10 @@ package jakarta.security.auth.message;
import javax.security.auth.Subject;
+/**
+ * Defines the contract for client-side authentication in JASPIC. A ClientAuth implementation authenticates outbound
+ * requests and validates inbound responses in a client-to-server communication pattern.
+ */
public interface ClientAuth {
/**
diff --git a/java/jakarta/security/auth/message/MessageInfo.java b/java/jakarta/security/auth/message/MessageInfo.java
index 4fd1e18f21..cb9c760132 100644
--- a/java/jakarta/security/auth/message/MessageInfo.java
+++ b/java/jakarta/security/auth/message/MessageInfo.java
@@ -18,15 +18,53 @@ package jakarta.security.auth.message;
import java.util.Map;
+/**
+ * Represents the request and response messages associated with a
+ * message-based authentication exchange. The {@code MessageInfo} object
+ * provides access to the request and response message objects, as well
+ * as a map of additional context information. The types of the request
+ * and response message objects are protocol-specific.
+ */
public interface MessageInfo {
+ /**
+ * Returns the request message object associated with this
+ * authentication exchange. The type of the returned object is
+ * protocol-specific.
+ *
+ * @return the request message object, or {@code null} if not available
+ */
Object getRequestMessage();
+ /**
+ * Returns the response message object associated with this
+ * authentication exchange. The type of the returned object is
+ * protocol-specific.
+ *
+ * @return the response message object, or {@code null} if not available
+ */
Object getResponseMessage();
+ /**
+ * Sets the request message object for this authentication exchange.
+ *
+ * @param request the request message object
+ */
void setRequestMessage(Object request);
+ /**
+ * Sets the response message object for this authentication exchange.
+ *
+ * @param response the response message object
+ */
void setResponseMessage(Object response);
+ /**
+ * Returns a map of additional context information associated with
+ * this authentication exchange. The map may contain protocol-specific
+ * attributes such as message headers.
+ *
+ * @return a {@code Map} of context information, or {@code null} if not available
+ */
Map<String,Object> getMap();
}
diff --git a/java/jakarta/security/auth/message/MessagePolicy.java b/java/jakarta/security/auth/message/MessagePolicy.java
index 3237ab42d6..7f0f3b2d12 100644
--- a/java/jakarta/security/auth/message/MessagePolicy.java
+++ b/java/jakarta/security/auth/message/MessagePolicy.java
@@ -16,11 +16,28 @@
*/
package jakarta.security.auth.message;
+/**
+ * Defines the security policy requirements for a message-based
+ * authentication module. A {@code MessagePolicy} specifies the target
+ * policies that determine which messages require authentication and the
+ * level of protection required.
+ */
public class MessagePolicy {
private final TargetPolicy[] targetPolicies;
private final boolean mandatory;
+ /**
+ * Creates a new {@code MessagePolicy} with the specified target
+ * policies and mandatory flag.
+ *
+ * @param targetPolicies the array of {@code TargetPolicy} objects
+ * defining the policy requirements; must not be {@code null}
+ * @param mandatory {@code true} if the policy is mandatory and
+ * authentication must succeed; {@code false} if the policy
+ * is optional
+ * @throws IllegalArgumentException if {@code targetPolicies} is {@code null}
+ */
public MessagePolicy(TargetPolicy[] targetPolicies, boolean mandatory) {
if (targetPolicies == null) {
throw new IllegalArgumentException("targetPolicies is null");
@@ -29,10 +46,23 @@ public class MessagePolicy {
this.mandatory = mandatory;
}
+ /**
+ * Indicates whether this policy is mandatory. If mandatory, the
+ * authentication module must enforce the policy and authentication
+ * will fail if the policy cannot be satisfied.
+ *
+ * @return {@code true} if the policy is mandatory, {@code false} otherwise
+ */
public boolean isMandatory() {
return mandatory;
}
+ /**
+ * Returns the target policies associated with this message policy.
+ *
+ * @return an array of {@code TargetPolicy} objects, or {@code null}
+ * if no target policies are defined
+ */
public TargetPolicy[] getTargetPolicies() {
if (targetPolicies.length == 0) {
return null;
@@ -40,29 +70,87 @@ public class MessagePolicy {
return targetPolicies;
}
+ /**
+ * Defines the level of protection to be applied to a message.
+ * A protection policy specifies whether the sender, content,
+ * or recipient of a message must be authenticated.
+ */
public interface ProtectionPolicy {
+ /**
+ * Identifier for a policy that requires authentication of the sender.
+ */
String AUTHENTICATE_SENDER = "#authenticateSender";
+
+ /**
+ * Identifier for a policy that requires authentication of the message content.
+ */
String AUTHENTICATE_CONTENT = "#authenticateContent";
+
+ /**
+ * Identifier for a policy that requires authentication of the recipient.
+ */
String AUTHENTICATE_RECIPIENT = "#authenticateRecipient";
+ /**
+ * Returns the unique identifier for this protection policy.
+ *
+ * @return the string identifier for this policy
+ */
String getID();
}
+ /**
+ * Defines how to extract target information from a message for
+ * policy evaluation. A target determines which messages are
+ * subject to a particular {@code TargetPolicy}.
+ */
public interface Target {
+ /**
+ * Retrieves the target value from the given message.
+ *
+ * @param messageInfo the message containing the target information
+ * @return the target value extracted from the message
+ */
Object get(MessageInfo messageInfo);
+ /**
+ * Removes the target value from the given message.
+ *
+ * @param messageInfo the message from which to remove the target
+ */
void remove(MessageInfo messageInfo);
+ /**
+ * Stores the target value in the given message.
+ *
+ * @param messageInfo the message in which to store the target
+ * @param data the target value to store
+ */
void put(MessageInfo messageInfo, Object data);
}
+ /**
+ * Associates a set of targets with a protection policy. A
+ * {@code TargetPolicy} defines the protection requirements for
+ * messages that match the specified targets.
+ */
public static class TargetPolicy {
private final Target[] targets;
private final ProtectionPolicy protectionPolicy;
+ /**
+ * Creates a new {@code TargetPolicy} with the specified targets
+ * and protection policy.
+ *
+ * @param targets the array of {@code Target} objects, or {@code null}
+ * if not applicable
+ * @param protectionPolicy the {@code ProtectionPolicy} to apply;
+ * must not be {@code null}
+ * @throws IllegalArgumentException if {@code protectionPolicy} is {@code null}
+ */
public TargetPolicy(Target[] targets, ProtectionPolicy protectionPolicy) {
if (protectionPolicy == null) {
throw new IllegalArgumentException("protectionPolicy is null");
@@ -71,6 +159,12 @@ public class MessagePolicy {
this.protectionPolicy = protectionPolicy;
}
+ /**
+ * Returns the targets associated with this target policy.
+ *
+ * @return an array of {@code Target} objects, or {@code null}
+ * if no targets are defined
+ */
public Target[] getTargets() {
if (targets == null || targets.length == 0) {
return null;
@@ -78,6 +172,11 @@ public class MessagePolicy {
return targets;
}
+ /**
+ * Returns the protection policy associated with this target policy.
+ *
+ * @return the {@code ProtectionPolicy} for this target policy
+ */
public ProtectionPolicy getProtectionPolicy() {
return protectionPolicy;
}
diff --git a/java/jakarta/security/auth/message/ServerAuth.java b/java/jakarta/security/auth/message/ServerAuth.java
index 8df08f055a..1508051b9d 100644
--- a/java/jakarta/security/auth/message/ServerAuth.java
+++ b/java/jakarta/security/auth/message/ServerAuth.java
@@ -18,6 +18,13 @@ package jakarta.security.auth.message;
import javax.security.auth.Subject;
+/**
+ * Provides server-side authentication of requests and response signing.
+ * <p>
+ * This interface defines the contract for authenticating incoming requests
+ * and optionally securing outgoing responses in a server-side context.
+ * Implementations are typically obtained through a {@link jakarta.security.auth.message.config.ServerAuthContext}.
+ */
public interface ServerAuth {
/**
diff --git a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
index c29fca9002..11aaf37c9e 100644
--- a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
+++ b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
@@ -22,8 +22,9 @@ import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
/**
- * Callback that enables an authentication module to inform the runtime of the call principal or name of the caller
- * principal.
+ * Callback that enables an authentication module to inform the runtime of the caller principal or name of the
+ * caller principal. The callback handler populates the given Subject with the authenticated principal, or returns
+ * the principal/name that was provided.
*/
public class CallerPrincipalCallback implements Callback {
@@ -31,26 +32,55 @@ public class CallerPrincipalCallback implements Callback {
private final Principal principal;
private final String name;
+ /**
+ * Constructs a callback with a Subject and a Principal. The callback handler will add the principal to the
+ * subject.
+ *
+ * @param subject the subject to which the principal will be added
+ * @param principal the principal representing the caller
+ */
public CallerPrincipalCallback(Subject subject, Principal principal) {
this.subject = subject;
this.principal = principal;
this.name = null;
}
+ /**
+ * Constructs a callback with a Subject and a caller name. The callback handler will create a principal from
+ * the name and add it to the subject.
+ *
+ * @param subject the subject to which the principal will be added
+ * @param name the name of the caller
+ */
public CallerPrincipalCallback(Subject subject, String name) {
this.subject = subject;
this.principal = null;
this.name = name;
}
+ /**
+ * Returns the Subject associated with this callback.
+ *
+ * @return the Subject
+ */
public Subject getSubject() {
return subject;
}
+ /**
+ * Returns the Principal associated with this callback, or {@code null} if a name was provided instead.
+ *
+ * @return the Principal, or {@code null}
+ */
public Principal getPrincipal() {
return principal;
}
+ /**
+ * Returns the name associated with this callback, or {@code null} if a Principal was provided instead.
+ *
+ * @return the name, or {@code null}
+ */
public String getName() {
return name;
}
diff --git a/java/jakarta/security/auth/message/callback/CertStoreCallback.java b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
index d8aef96cb2..f30a9dbf95 100644
--- a/java/jakarta/security/auth/message/callback/CertStoreCallback.java
+++ b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
@@ -21,19 +21,33 @@ import java.security.cert.CertStore;
import javax.security.auth.callback.Callback;
/**
- * Callback that enables a runtime to inform authentication modules of the CertStore to use.
+ * Callback that enables a runtime to inform authentication modules of the {@link CertStore} to use for certificate
+ * validation. The runtime populates the CertStore, and the authentication module retrieves it.
*/
public class CertStoreCallback implements Callback {
private CertStore certStore;
+ /**
+ * Constructs an empty CertStoreCallback. The runtime will populate the CertStore via {@link #setCertStore}.
+ */
public CertStoreCallback() {
}
+ /**
+ * Sets the CertStore to be used for certificate validation.
+ *
+ * @param certStore the CertStore
+ */
public void setCertStore(CertStore certStore) {
this.certStore = certStore;
}
+ /**
+ * Returns the CertStore set by the runtime.
+ *
+ * @return the CertStore, or {@code null} if not yet set
+ */
public CertStore getCertStore() {
return certStore;
}
diff --git a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
index f5b2e55ffe..4f053e22f0 100644
--- a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
+++ b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
@@ -21,21 +21,40 @@ import javax.security.auth.callback.Callback;
/**
* Callback that enables an authentication module to inform the runtime of the groups a user is in.
+ * The callback handler populates the given Subject with the group principals, or returns the
+ * group names that were provided.
*/
public class GroupPrincipalCallback implements Callback {
private final Subject subject;
private final String[] groups;
+ /**
+ * Constructs a callback with a Subject and an array of group names. The callback handler
+ * will create principals for the group names and add them to the subject.
+ *
+ * @param subject the subject to which the group principals will be added
+ * @param groups the group names associated with the caller
+ */
public GroupPrincipalCallback(Subject subject, String[] groups) {
this.subject = subject;
this.groups = groups;
}
+ /**
+ * Returns the Subject associated with this callback.
+ *
+ * @return the Subject
+ */
public Subject getSubject() {
return subject;
}
+ /**
+ * Returns the group names associated with this callback.
+ *
+ * @return the group names
+ */
public String[] getGroups() {
return groups;
}
diff --git a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
index ae9f6bdecc..d552255736 100644
--- a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
+++ b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
@@ -22,8 +22,10 @@ import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
/**
- * Callback that enables an authentication module to supply a username and password (to a runtime?) and determine if the
- * result of validation.
+ * A callback that enables an authentication module to supply a username
+ * and password to the runtime and obtain the result of password validation.
+ * The runtime validates the credentials and updates the {@code Subject}
+ * if authentication succeeds.
*/
public class PasswordValidationCallback implements Callback {
@@ -32,33 +34,76 @@ public class PasswordValidationCallback implements Callback {
private char[] password;
private boolean result;
+ /**
+ * Creates a new {@code PasswordValidationCallback} with the specified
+ * subject, username, and password.
+ *
+ * @param subject the {@code Subject} to be populated upon successful
+ * authentication
+ * @param username the username to validate
+ * @param password the password to validate
+ */
public PasswordValidationCallback(Subject subject, String username, char[] password) {
this.subject = subject;
this.username = username;
this.password = password;
}
+ /**
+ * Returns the {@code Subject} associated with this callback. The
+ * runtime populates this subject with authentication information
+ * upon successful validation.
+ *
+ * @return the {@code Subject} for this callback
+ */
public Subject getSubject() {
return subject;
}
+ /**
+ * Returns the username to be validated.
+ *
+ * @return the username
+ */
public String getUsername() {
return username;
}
+ /**
+ * Returns the password to be validated.
+ *
+ * @return the password character array
+ */
public char[] getPassword() {
return password;
}
+ /**
+ * Clears the password from memory for security purposes. After
+ * calling this method, {@link #getPassword()} will return an empty
+ * character array.
+ */
public void clearPassword() {
Arrays.fill(password, (char) 0);
password = new char[0];
}
+ /**
+ * Sets the result of the password validation performed by the runtime.
+ *
+ * @param result {@code true} if the password validation succeeded,
+ * {@code false} otherwise
+ */
public void setResult(boolean result) {
this.result = result;
}
+ /**
+ * Returns the result of the password validation.
+ *
+ * @return {@code true} if the password was validated successfully,
+ * {@code false} otherwise
+ */
public boolean getResult() {
return result;
}
diff --git a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
index 853ca02600..c3aab997d6 100644
--- a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
+++ b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
@@ -24,9 +24,11 @@ import javax.security.auth.callback.Callback;
import javax.security.auth.x500.X500Principal;
/**
- * Callback that enables an authentication module to request a certificate chain and private key from the runtime. The
- * information specifying the chain and key may be an alias, a digest, a subject key, or an issuer ID. Other request
- * types may be supported.
+ * A callback that enables an authentication module to request a
+ * certificate chain and private key from the runtime. The request
+ * identifies the desired key material using one of several {@link Request}
+ * subtypes, such as keystore alias, certificate digest, subject key
+ * identifier, or issuer and serial number.
*/
public class PrivateKeyCallback implements Callback {
@@ -34,87 +36,192 @@ public class PrivateKeyCallback implements Callback {
private Certificate[] chain;
private PrivateKey key;
+ /**
+ * Creates a new {@code PrivateKeyCallback} with the specified request.
+ *
+ * @param request the {@code Request} object identifying the desired
+ * certificate chain and private key
+ */
public PrivateKeyCallback(Request request) {
this.request = request;
}
+ /**
+ * Returns the request associated with this callback.
+ *
+ * @return the {@code Request} object
+ */
public Request getRequest() {
return request;
}
+ /**
+ * Sets the private key and certificate chain resolved by the runtime
+ * in response to the request.
+ *
+ * @param key the resolved {@code PrivateKey}
+ * @param chain the corresponding certificate chain
+ */
public void setKey(PrivateKey key, Certificate[] chain) {
this.key = key;
this.chain = chain;
}
+ /**
+ * Returns the private key resolved by the runtime.
+ *
+ * @return the {@code PrivateKey}, or {@code null} if not yet resolved
+ */
public PrivateKey getKey() {
return key;
}
+ /**
+ * Returns the certificate chain resolved by the runtime.
+ *
+ * @return the certificate chain, or {@code null} if not yet resolved
+ */
public Certificate[] getChain() {
return chain;
}
+ /**
+ * Base interface for private key requests. Implementations specify
+ * the criteria by which the runtime should locate the desired
+ * certificate chain and private key.
+ */
public interface Request {
}
+ /**
+ * A request to retrieve a certificate chain and private key by
+ * keystore alias.
+ */
public static class AliasRequest implements Request {
private final String alias;
+ /**
+ * Creates a new {@code AliasRequest} with the specified keystore alias.
+ *
+ * @param alias the keystore alias identifying the desired key entry
+ */
public AliasRequest(String alias) {
this.alias = alias;
}
+ /**
+ * Returns the keystore alias for this request.
+ *
+ * @return the keystore alias
+ */
public String getAlias() {
return alias;
}
}
+ /**
+ * A request to retrieve a certificate chain and private key by
+ * certificate digest value.
+ */
public static class DigestRequest implements Request {
private final byte[] digest;
private final String algorithm;
+ /**
+ * Creates a new {@code DigestRequest} with the specified digest
+ * value and digest algorithm.
+ *
+ * @param digest the digest value of the desired certificate
+ * @param algorithm the digest algorithm used to produce the digest
+ */
public DigestRequest(byte[] digest, String algorithm) {
this.digest = digest;
this.algorithm = algorithm;
}
+ /**
+ * Returns the digest value for this request.
+ *
+ * @return the digest byte array
+ */
public byte[] getDigest() {
return digest;
}
+ /**
+ * Returns the digest algorithm used for this request.
+ *
+ * @return the algorithm name
+ */
public String getAlgorithm() {
return algorithm;
}
}
+ /**
+ * A request to retrieve a certificate chain and private key by
+ * the Subject Key Identifier extension value.
+ */
public static class SubjectKeyIDRequest implements Request {
private final byte[] subjectKeyID;
+ /**
+ * Creates a new {@code SubjectKeyIDRequest} with the specified
+ * subject key identifier.
+ *
+ * @param subjectKeyID the Subject Key Identifier extension value
+ * from the desired certificate
+ */
public SubjectKeyIDRequest(byte[] subjectKeyID) {
this.subjectKeyID = subjectKeyID;
}
+ /**
+ * Returns the subject key identifier for this request.
+ *
+ * @return the Subject Key Identifier byte array
+ */
public byte[] getSubjectKeyID() {
return subjectKeyID;
}
}
+ /**
+ * A request to retrieve a certificate chain and private key by
+ * the issuer distinguished name and certificate serial number.
+ */
public static class IssuerSerialNumRequest implements Request {
private final X500Principal issuer;
private final BigInteger serialNum;
+ /**
+ * Creates a new {@code IssuerSerialNumRequest} with the specified
+ * issuer and serial number.
+ *
+ * @param issuer the issuer distinguished name of the desired certificate
+ * @param serialNum the serial number of the desired certificate
+ */
public IssuerSerialNumRequest(X500Principal issuer, BigInteger serialNum) {
this.issuer = issuer;
this.serialNum = serialNum;
}
+ /**
+ * Returns the issuer distinguished name for this request.
+ *
+ * @return the {@code X500Principal} representing the issuer
+ */
public X500Principal getIssuer() {
return issuer;
}
+ /**
+ * Returns the certificate serial number for this request.
+ *
+ * @return the serial number as a {@code BigInteger}
+ */
public BigInteger getSerialNum() {
return serialNum;
}
diff --git a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
index b3a02ad938..7cf47cdec8 100644
--- a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
+++ b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
@@ -28,33 +28,70 @@ public class SecretKeyCallback implements Callback {
private final Request request;
private SecretKey key;
+ /**
+ * Constructs a SecretKeyCallback with the specified request.
+ *
+ * @param request The request describing the secret key to obtain
+ */
public SecretKeyCallback(Request request) {
this.request = request;
}
+ /**
+ * Returns the request associated with this callback.
+ *
+ * @return The request describing the secret key to obtain
+ */
public Request getRequest() {
return request;
}
+ /**
+ * Sets the secret key obtained by the runtime.
+ *
+ * @param key The secret key
+ */
public void setKey(SecretKey key) {
this.key = key;
}
+ /**
+ * Returns the secret key.
+ *
+ * @return The secret key, or {@code null} if not set
+ */
public SecretKey getKey() {
return key;
}
+ /**
+ * Represents a request for a secret key.
+ * Implementations specify the criteria for locating the desired key.
+ */
public interface Request {
}
+ /**
+ * A request for a secret key identified by its alias.
+ */
public static class AliasRequest implements Request {
private final String alias;
+ /**
+ * Constructs an AliasRequest with the specified alias.
+ *
+ * @param alias The alias of the secret key to obtain
+ */
public AliasRequest(String alias) {
this.alias = alias;
}
+ /**
+ * Returns the alias of the requested secret key.
+ *
+ * @return The alias string
+ */
public String getAlias() {
return alias;
}
diff --git a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
index 9bafa9a26b..a6a367ba19 100644
--- a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
+++ b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
@@ -27,10 +27,26 @@ public class TrustStoreCallback implements Callback {
private KeyStore trustStore;
+ /**
+ * Constructs a new TrustStoreCallback.
+ */
+ public TrustStoreCallback() {
+ }
+
+ /**
+ * Sets the trust store to be used for certificate validation.
+ *
+ * @param trustStore The trust store containing trusted certificates
+ */
public void setTrustStore(KeyStore trustStore) {
this.trustStore = trustStore;
}
+ /**
+ * Returns the trust store.
+ *
+ * @return The trust store, or {@code null} if not set
+ */
public KeyStore getTrustStore() {
return trustStore;
}
diff --git a/java/jakarta/security/auth/message/config/AuthConfig.java b/java/jakarta/security/auth/message/config/AuthConfig.java
index 099cccee8d..7e3e5e0572 100644
--- a/java/jakarta/security/auth/message/config/AuthConfig.java
+++ b/java/jakarta/security/auth/message/config/AuthConfig.java
@@ -18,15 +18,46 @@ package jakarta.security.auth.message.config;
import jakarta.security.auth.message.MessageInfo;
+/**
+ * Provides configuration information for a JASPIC authentication mechanism. An AuthConfig defines the message layer,
+ * application context, and authentication context ID for a given message, and indicates whether the mechanism is
+ * protected.
+ */
public interface AuthConfig {
+ /**
+ * Returns the message layer for which this configuration applies.
+ *
+ * @return the message layer
+ */
String getMessageLayer();
+ /**
+ * Returns the application context for which this configuration applies.
+ *
+ * @return the application context
+ */
String getAppContext();
+ /**
+ * Determines the authentication context ID for the given message.
+ *
+ * @param messageInfo the message information used to determine the context ID
+ *
+ * @return the authentication context ID, or {@code null} if no context applies
+ */
String getAuthContextID(MessageInfo messageInfo);
+ /**
+ * Refreshes the configuration, reloading any changed settings.
+ */
void refresh();
+ /**
+ * Indicates whether the authentication mechanism is protected, meaning that the configuration data is stored
+ * securely.
+ *
+ * @return {@code true} if the mechanism is protected, {@code false} otherwise
+ */
boolean isProtected();
}
diff --git a/java/jakarta/security/auth/message/config/AuthConfigFactory.java b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
index e8f4938ad6..7d56046cf3 100644
--- a/java/jakarta/security/auth/message/config/AuthConfigFactory.java
+++ b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
@@ -21,8 +21,17 @@ import java.util.Map;
import jakarta.security.auth.message.module.ServerAuthModule;
+/**
+ * Factory for obtaining and managing {@link AuthConfigProvider} instances. The AuthConfigFactory is responsible for
+ * discovering, registering, and providing configuration providers for JASPIC authentication modules. Use
+ * {@link #getFactory()} to obtain the singleton instance.
+ */
public abstract class AuthConfigFactory {
+ /**
+ * The name of the {@link java.security.Security} property used to specify the AuthConfigFactory implementation
+ * class.
+ */
public static final String DEFAULT_FACTORY_SECURITY_PROPERTY = "authconfigprovider.factory";
private static final String DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL =
@@ -30,9 +39,19 @@ public abstract class AuthConfigFactory {
private static volatile AuthConfigFactory factory;
+ /**
+ * Protected constructor for subclasses.
+ */
public AuthConfigFactory() {
}
+ /**
+ * Returns the singleton AuthConfigFactory instance. If no instance has been set via {@link #setFactory}, the
+ * factory class is discovered from the {@link java.security.Security} property
+ * {@value #DEFAULT_FACTORY_SECURITY_PROPERTY}, or falls back to a default implementation.
+ *
+ * @return the AuthConfigFactory instance
+ */
public static AuthConfigFactory getFactory() {
if (factory != null) {
return factory;
@@ -61,27 +80,97 @@ public abstract class AuthConfigFactory {
return factory;
}
+ /**
+ * Programmatically sets the AuthConfigFactory instance. This method is typically used by containers to provide
+ * their own implementation.
+ *
+ * @param factory the AuthConfigFactory instance to set
+ */
public static synchronized void setFactory(AuthConfigFactory factory) {
AuthConfigFactory.factory = factory;
}
+ /**
+ * Returns the {@link AuthConfigProvider} for the specified message layer and application context.
+ *
+ * @param layer the message layer
+ * @param appContext the application context
+ * @param listener the registration listener to attach
+ *
+ * @return the AuthConfigProvider, or {@code null} if none is available
+ */
public abstract AuthConfigProvider getConfigProvider(String layer, String appContext,
RegistrationListener listener);
+ /**
+ * Registers an AuthConfigProvider by class name with the given properties.
+ *
+ * @param className the fully qualified class name of the AuthConfigProvider
+ * @param properties the configuration properties
+ * @param layer the message layer
+ * @param appContext the application context
+ * @param description a description of the registration
+ *
+ * @return a unique registration ID
+ */
public abstract String registerConfigProvider(String className, Map<String,String> properties, String layer,
String appContext, String description);
+ /**
+ * Registers an AuthConfigProvider instance.
+ *
+ * @param provider the AuthConfigProvider to register
+ * @param layer the message layer
+ * @param appContext the application context
+ * @param description a description of the registration
+ *
+ * @return a unique registration ID
+ */
public abstract String registerConfigProvider(AuthConfigProvider provider, String layer, String appContext,
String description);
+ /**
+ * Removes a registration by its ID.
+ *
+ * @param registrationID the registration ID to remove
+ *
+ * @return {@code true} if the registration was removed, {@code false} if it did not exist
+ */
public abstract boolean removeRegistration(String registrationID);
+ /**
+ * Detaches a listener from all registrations matching the given layer and application context, returning the
+ * affected registration IDs.
+ *
+ * @param listener the listener to detach
+ * @param layer the message layer
+ * @param appContext the application context
+ *
+ * @return an array of registration IDs from which the listener was detached
+ */
public abstract String[] detachListener(RegistrationListener listener, String layer, String appContext);
+ /**
+ * Returns the registration IDs associated with the given AuthConfigProvider.
+ *
+ * @param provider the AuthConfigProvider
+ *
+ * @return an array of registration IDs
+ */
public abstract String[] getRegistrationIDs(AuthConfigProvider provider);
+ /**
+ * Returns the {@link RegistrationContext} for the given registration ID.
+ *
+ * @param registrationID the registration ID
+ *
+ * @return the RegistrationContext, or {@code null} if the ID is not found
+ */
public abstract RegistrationContext getRegistrationContext(String registrationID);
+ /**
+ * Refreshes all registered AuthConfigProviders, causing them to reload their configuration.
+ */
public abstract void refresh();
/**
@@ -118,14 +207,37 @@ public abstract class AuthConfigFactory {
return DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL;
}
+ /**
+ * Provides information about a registered {@link AuthConfigProvider}.
+ */
public interface RegistrationContext {
+ /**
+ * Returns the message layer for this registration.
+ *
+ * @return the message layer
+ */
String getMessageLayer();
+ /**
+ * Returns the application context for this registration.
+ *
+ * @return the application context
+ */
String getAppContext();
+ /**
+ * Returns the description of this registration.
+ *
+ * @return the description
+ */
String getDescription();
+ /**
+ * Indicates whether this registration persists beyond the current container lifecycle.
+ *
+ * @return {@code true} if the registration is persistent, {@code false} otherwise
+ */
boolean isPersistent();
}
}
diff --git a/java/jakarta/security/auth/message/config/AuthConfigProvider.java b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
index 66410a7e13..9f42dafd06 100644
--- a/java/jakarta/security/auth/message/config/AuthConfigProvider.java
+++ b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
@@ -20,11 +20,41 @@ import javax.security.auth.callback.CallbackHandler;
import jakarta.security.auth.message.AuthException;
+/**
+ * Provides {@link ClientAuthConfig} and {@link ServerAuthConfig} instances to JASPIC authentication modules. An
+ * AuthConfigProvider is responsible for loading authentication configuration from a source (e.g., a configuration
+ * file, database, or service) and making it available to the authentication modules.
+ */
public interface AuthConfigProvider {
+ /**
+ * Returns the client-side authentication configuration for the specified layer and application context.
+ *
+ * @param layer the message layer
+ * @param appContext the application context
+ * @param handler the callback handler for obtaining sensitive configuration data
+ *
+ * @return the ClientAuthConfig, or {@code null} if no configuration is available
+ *
+ * @throws AuthException if an error occurs while retrieving the configuration
+ */
ClientAuthConfig getClientAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
+ /**
+ * Returns the server-side authentication configuration for the specified layer and application context.
+ *
+ * @param layer the message layer
+ * @param appContext the application context
+ * @param handler the callback handler for obtaining sensitive configuration data
+ *
+ * @return the ServerAuthConfig, or {@code null} if no configuration is available
+ *
+ * @throws AuthException if an error occurs while retrieving the configuration
+ */
ServerAuthConfig getServerAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
+ /**
+ * Refreshes the configuration, reloading any changed settings from the underlying source.
+ */
void refresh();
}
diff --git a/java/jakarta/security/auth/message/config/ClientAuthConfig.java b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
index f332f0fea6..8c588bda46 100644
--- a/java/jakarta/security/auth/message/config/ClientAuthConfig.java
+++ b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
@@ -22,8 +22,23 @@ import javax.security.auth.Subject;
import jakarta.security.auth.message.AuthException;
+/**
+ * Client-side authentication configuration obtained from an {@link AuthConfigProvider}. A ClientAuthConfig provides
+ * the configuration needed to create a {@link ClientAuthContext} for authenticating outbound requests.
+ */
public interface ClientAuthConfig extends AuthConfig {
+ /**
+ * Creates a {@link ClientAuthContext} for the specified authentication context ID.
+ *
+ * @param authContextID the authentication context ID
+ * @param clientSubject the subject representing the client, to be populated upon successful authentication
+ * @param properties additional configuration properties
+ *
+ * @return the ClientAuthContext, or {@code null} if the authContextID is not recognized
+ *
+ * @throws AuthException if an error occurs while creating the context
+ */
ClientAuthContext getAuthContext(String authContextID, Subject clientSubject, Map<String,Object> properties)
throws AuthException;
}
diff --git a/java/jakarta/security/auth/message/config/ClientAuthContext.java b/java/jakarta/security/auth/message/config/ClientAuthContext.java
index 53280c7822..1c7f95c53b 100644
--- a/java/jakarta/security/auth/message/config/ClientAuthContext.java
+++ b/java/jakarta/security/auth/message/config/ClientAuthContext.java
@@ -18,5 +18,10 @@ package jakarta.security.auth.message.config;
import jakarta.security.auth.message.ClientAuth;
+/**
+ * Runtime context for client-side JASPIC authentication. A ClientAuthContext is created by a
+ * {@link ClientAuthConfig} and performs the actual authentication of outbound requests and validation of inbound
+ * responses.
+ */
public interface ClientAuthContext extends ClientAuth {
}
diff --git a/java/jakarta/security/auth/message/config/RegistrationListener.java b/java/jakarta/security/auth/message/config/RegistrationListener.java
index 05bec1c163..9c3053660b 100644
--- a/java/jakarta/security/auth/message/config/RegistrationListener.java
+++ b/java/jakarta/security/auth/message/config/RegistrationListener.java
@@ -16,7 +16,16 @@
*/
package jakarta.security.auth.message.config;
+/**
+ * Listener interface for JASPIC registration events.
+ */
public interface RegistrationListener {
+ /**
+ * Notifies the listener of a registration event.
+ *
+ * @param layer the authentication layer
+ * @param appContext the application context
+ */
void notify(String layer, String appContext);
}
diff --git a/java/jakarta/security/auth/message/config/ServerAuthConfig.java b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
index a8bc9c728c..f970ea5466 100644
--- a/java/jakarta/security/auth/message/config/ServerAuthConfig.java
+++ b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
@@ -22,8 +22,20 @@ import javax.security.auth.Subject;
import jakarta.security.auth.message.AuthException;
+/**
+ * Server-side authentication configuration obtained from an {@link AuthConfigProvider}.
+ */
public interface ServerAuthConfig extends AuthConfig {
+ /**
+ * Returns the {@link ServerAuthContext} for the given authentication context ID.
+ *
+ * @param authContextID the authentication context identifier
+ * @param serviceSubject the service subject
+ * @param properties the configuration properties
+ * @return the server authentication context
+ * @throws AuthException if an error occurs during authentication context creation
+ */
ServerAuthContext getAuthContext(String authContextID, Subject serviceSubject, Map<String,Object> properties)
throws AuthException;
}
diff --git a/java/jakarta/security/auth/message/config/ServerAuthContext.java b/java/jakarta/security/auth/message/config/ServerAuthContext.java
index bbff396988..4c668f7ba5 100644
--- a/java/jakarta/security/auth/message/config/ServerAuthContext.java
+++ b/java/jakarta/security/auth/message/config/ServerAuthContext.java
@@ -18,5 +18,12 @@ package jakarta.security.auth.message.config;
import jakarta.security.auth.message.ServerAuth;
+/**
+ * Provides server-side authentication of requests and response signing.
+ * <p>
+ * This interface extends {@link ServerAuth} and is obtained from a
+ * {@link ServerAuthConfig}. It is used by the container to authenticate
+ * incoming requests and secure outgoing responses.
+ */
public interface ServerAuthContext extends ServerAuth {
}
diff --git a/java/jakarta/security/auth/message/module/ClientAuthModule.java b/java/jakarta/security/auth/message/module/ClientAuthModule.java
index b0569a462c..ef0d8be7a4 100644
--- a/java/jakarta/security/auth/message/module/ClientAuthModule.java
+++ b/java/jakarta/security/auth/message/module/ClientAuthModule.java
@@ -24,10 +24,31 @@ import jakarta.security.auth.message.AuthException;
import jakarta.security.auth.message.ClientAuth;
import jakarta.security.auth.message.MessagePolicy;
+/**
+ * A pluggable client-side authentication module in JASPIC. A ClientAuthModule implements the authentication logic
+ * for client-side operations and is initialized with message policies, a callback handler, and configuration
+ * options.
+ */
public interface ClientAuthModule extends ClientAuth {
+ /**
+ * Initializes the authentication module with the given policies, callback handler, and options. This method is
+ * called once when the module is created.
+ *
+ * @param requestPolicy the message policy for requests
+ * @param responsePolicy the message policy for responses
+ * @param handler the callback handler for obtaining sensitive data
+ * @param options configuration options for the module
+ *
+ * @throws AuthException if initialization fails
+ */
void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
Map<String,Object> options) throws AuthException;
+ /**
+ * Returns the array of MessageInfo implementation classes supported by this module.
+ *
+ * @return an array of supported MessageInfo classes
+ */
Class<?>[] getSupportedMessageTypes();
}
diff --git a/java/jakarta/security/auth/message/module/ServerAuthModule.java b/java/jakarta/security/auth/message/module/ServerAuthModule.java
index 3518bea61d..66e7297fbb 100644
--- a/java/jakarta/security/auth/message/module/ServerAuthModule.java
+++ b/java/jakarta/security/auth/message/module/ServerAuthModule.java
@@ -24,10 +24,35 @@ import jakarta.security.auth.message.AuthException;
import jakarta.security.auth.message.MessagePolicy;
import jakarta.security.auth.message.ServerAuth;
+/**
+ * Provides server-side authentication of requests and response signing.
+ * <p>
+ * This interface extends {@link ServerAuth} and is implemented by authentication
+ * module providers. It is initialized by the container and provides the actual
+ * authentication logic for server-side message authentication.
+ */
public interface ServerAuthModule extends ServerAuth {
+ /**
+ * Initialize the authentication module.
+ * <p>
+ * This method is called by the container to initialize the module with the
+ * request and response policies, a callback handler, and a set of options.
+ *
+ * @param requestPolicy The policy for the request message
+ * @param responsePolicy The policy for the response message
+ * @param handler The callback handler used to obtain credentials
+ * @param options The options provided to the module
+ *
+ * @throws AuthException If an error occurs during initialization
+ */
void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
Map<String,Object> options) throws AuthException;
+ /**
+ * Returns the array of message types supported by the module.
+ *
+ * @return The array of supported message type classes
+ */
Class<?>[] getSupportedMessageTypes();
}
diff --git a/java/jakarta/servlet/AsyncContext.java b/java/jakarta/servlet/AsyncContext.java
index 7b952e6394..5ba0e7eb53 100644
--- a/java/jakarta/servlet/AsyncContext.java
+++ b/java/jakarta/servlet/AsyncContext.java
@@ -54,21 +54,32 @@ public interface AsyncContext {
String ASYNC_QUERY_STRING = "jakarta.servlet.async.query_string";
/**
- * @return a reference to the ServletRequest object
+ * Returns the {@link ServletRequest} associated with this asynchronous operation.
+ *
+ * @return the ServletRequest object
*/
ServletRequest getRequest();
/**
- * @return a reference to the ServletResponse object
+ * Returns the {@link ServletResponse} associated with this asynchronous operation.
+ *
+ * @return the ServletResponse object
*/
ServletResponse getResponse();
/**
- * @return true if the Request and Response are the original ones
+ * Determines whether the request and response objects are the original ones passed to
+ * {@link jakarta.servlet.http.HttpServletRequest#startAsync()}, or if they are new objects created by the
+ * container.
+ *
+ * @return {@code true} if the request and response are the original objects, {@code false} otherwise
*/
boolean hasOriginalRequestAndResponse();
/**
+ * Dispatches the request to the resource at the original request URI, as specified in the original request. After
+ * the dispatch, the async request processing is complete and the response is committed.
+ *
* @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
* is in asynchronous mode after
* {@link jakarta.servlet.http.HttpServletRequest#startAsync()} or
@@ -79,8 +90,12 @@ public interface AsyncContext {
void dispatch();
/**
- * @param path The path to which the request/response should be dispatched relative to the {@link ServletContext}
- * from which this async request was started.
+ * Dispatches the request to the resource at the specified path relative to the {@link ServletContext} from which
+ * this async request was started. After the dispatch, the async request processing is complete and the response
+ * is committed.
+ *
+ * @param path the path to which the request/response should be dispatched relative to the {@link ServletContext}
+ * from which this async request was started
*
* @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
* is in asynchronous mode after
@@ -92,9 +107,12 @@ public interface AsyncContext {
void dispatch(String path);
/**
- * @param path The path to which the request/response should be dispatched relative to the specified
- * {@link ServletContext}.
- * @param context The {@link ServletContext} to which the request/response should be dispatched.
+ * Dispatches the request to the resource at the specified path relative to the given {@link ServletContext}.
+ * After the dispatch, the async request processing is complete and the response is committed.
+ *
+ * @param path the path to which the request/response should be dispatched relative to the specified
+ * {@link ServletContext}
+ * @param context the {@link ServletContext} to which the request/response should be dispatched
*
* @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
* is in asynchronous mode after
diff --git a/java/jakarta/servlet/GenericFilter.java b/java/jakarta/servlet/GenericFilter.java
index 67b7962d79..ef6b8fb901 100644
--- a/java/jakarta/servlet/GenericFilter.java
+++ b/java/jakarta/servlet/GenericFilter.java
@@ -34,11 +34,18 @@ public abstract class GenericFilter implements Filter, FilterConfig, Serializabl
@Serial
private static final long serialVersionUID = 1L;
- /**
- * The filter configuration.
- */
+ /**
+ * The filter configuration.
+ */
private volatile FilterConfig filterConfig;
+ /**
+ * Constructs a new GenericFilter.
+ */
+ public GenericFilter() {
+ // NO-OP
+ }
+
@Override
public String getInitParameter(String name) {
diff --git a/java/jakarta/servlet/HttpConstraintElement.java b/java/jakarta/servlet/HttpConstraintElement.java
index 90e310295c..51b3c41a50 100644
--- a/java/jakarta/servlet/HttpConstraintElement.java
+++ b/java/jakarta/servlet/HttpConstraintElement.java
@@ -89,27 +89,27 @@ public class HttpConstraintElement {
}
/**
- * TODO
+ * Returns the empty role semantic for this constraint.
*
- * @return TODO
+ * @return The empty role semantic for this constraint
*/
public EmptyRoleSemantic getEmptyRoleSemantic() {
return emptyRoleSemantic;
}
/**
- * TODO
+ * Returns the transport guarantee for this constraint.
*
- * @return TODO
+ * @return The transport guarantee for this constraint
*/
public TransportGuarantee getTransportGuarantee() {
return transportGuarantee;
}
/**
- * TODO
+ * Returns the roles allowed for this constraint.
*
- * @return TODO
+ * @return The roles allowed for this constraint
*/
public String[] getRolesAllowed() {
return rolesAllowed;
diff --git a/java/jakarta/servlet/ServletContext.java b/java/jakarta/servlet/ServletContext.java
index 15eba5a3a5..adf8ececdf 100644
--- a/java/jakarta/servlet/ServletContext.java
+++ b/java/jakarta/servlet/ServletContext.java
@@ -551,7 +551,7 @@ public interface ServletContext {
*
* @since Servlet 3.0
*/
- Map<String,? extends ServletRegistration> getServletRegistrations();
+ Map<String, ? extends ServletRegistration> getServletRegistrations();
/**
* Add filter to context.
@@ -644,11 +644,11 @@ public interface ServletContext {
<T extends Filter> T createFilter(Class<T> c) throws ServletException;
/**
- * TODO SERVLET3 - Add comments
+ * Returns the {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists.
*
- * @param filterName TODO
+ * @param filterName The name of the filter for which to return the registration
*
- * @return TODO
+ * @return The {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists
*
* @throws UnsupportedOperationException If called from a
* {@link ServletContextListener#contextInitialized(ServletContextEvent)}
@@ -663,7 +663,10 @@ public interface ServletContext {
FilterRegistration getFilterRegistration(String filterName);
/**
- * @return TODO
+ * Returns an immutable Map of all the filter registrations for this web application, where the key is the filter
+ * name and the value is the {@link FilterRegistration} object.
+ *
+ * @return An immutable Map of all the filter registrations for this web application
*
* @throws UnsupportedOperationException If called from a
* {@link ServletContextListener#contextInitialized(ServletContextEvent)}
@@ -673,12 +676,15 @@ public interface ServletContext {
* {@link ServletContextListener} defined in a TLD would not be able to
* use this method.
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @since Servlet 3.0
*/
- Map<String,? extends FilterRegistration> getFilterRegistrations();
+ Map<String, ? extends FilterRegistration> getFilterRegistrations();
/**
- * @return TODO
+ * Returns the {@link SessionCookieConfig} object for this web application, which can be used to configure the
+ * session tracking cookie.
+ *
+ * @return The {@link SessionCookieConfig} object for this web application
*
* @throws UnsupportedOperationException If called from a
* {@link ServletContextListener#contextInitialized(ServletContextEvent)}
@@ -688,7 +694,7 @@ public interface ServletContext {
* {@link ServletContextListener} defined in a TLD would not be able to
* use this method.
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @since Servlet 3.0
*/
SessionCookieConfig getSessionCookieConfig();
@@ -735,10 +741,20 @@ public interface ServletContext {
Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
/**
- * TODO SERVLET3 - Add comments
+ * Adds a listener to this web application. The listener instance will be created by the container using the
+ * no-argument constructor of the given class.
*
- * @param className TODO
+ * @param className The fully qualified class name of the listener to add
*
+ * @throws ClassCastException If the class name does not implement {@link EventListener} or a
+ * subinterface recognized by the servlet container, or if a non-standard
+ * listener type is not packaged in a JAR file with a
+ * <code>listener</code> element in the <code>META-INF/services</code>
+ * directory
+ * @throws IllegalArgumentException If the lifecycle of a listener prohibits addition at runtime, or if the
+ * class has a {@link jakarta.servlet.annotation.WebListener} annotation
+ * that conflicts with the programmatic addition
+ * @throws IllegalStateException If the context has already been initialised
* @throws UnsupportedOperationException If called from a
* {@link ServletContextListener#contextInitialized(ServletContextEvent)}
* method of a {@link ServletContextListener} that was not defined in a
@@ -752,11 +768,20 @@ public interface ServletContext {
void addListener(String className);
/**
- * TODO SERVLET3 - Add comments
+ * Adds the given listener instance to this web application.
*
- * @param <T> TODO
- * @param t TODO
+ * @param <T> The type of listener being added
+ * @param t The listener instance to add
*
+ * @throws ClassCastException If the class of the listener instance does not implement
+ * {@link EventListener} or a subinterface recognized by the servlet
+ * container, or if a non-standard listener type is not packaged in a JAR
+ * file with a <code>listener</code> element in the
+ * <code>META-INF/services</code> directory
+ * @throws IllegalArgumentException If the lifecycle of a listener prohibits addition at runtime, or if the
+ * class has a {@link jakarta.servlet.annotation.WebListener} annotation
+ * that conflicts with the programmatic addition
+ * @throws IllegalStateException If the context has already been initialised
* @throws UnsupportedOperationException If called from a
* {@link ServletContextListener#contextInitialized(ServletContextEvent)}
* method of a {@link ServletContextListener} that was not defined in a
@@ -770,10 +795,19 @@ public interface ServletContext {
<T extends EventListener> void addListener(T t);
/**
- * TODO SERVLET3 - Add comments
+ * Adds a listener to this web application. The listener instance will be created by the container using the
+ * no-argument constructor of the given class.
*
- * @param listenerClass TODO
+ * @param listenerClass The class of the listener to add
*
+ * @throws ClassCastException If the class does not implement {@link EventListener} or a subinterface
+ * recognized by the servlet container, or if a non-standard listener type
+ * is not packaged in a JAR file with a <code>listener</code> element in
+ * the <code>META-INF/services</code> directory
+ * @throws IllegalArgumentException If the lifecycle of a listener prohibits addition at runtime, or if the
+ * class has a {@link jakarta.servlet.annotation.WebListener} annotation
+ * that conflicts with the programmatic addition
+ * @throws IllegalStateException If the context has already been initialised
* @throws UnsupportedOperationException If called from a
* {@link ServletContextListener#contextInitialized(ServletContextEvent)}
* method of a {@link ServletContextListener} that was not defined in a
@@ -787,14 +821,15 @@ public interface ServletContext {
void addListener(Class<? extends EventListener> listenerClass);
/**
- * TODO SERVLET3 - Add comments
+ * Creates a new instance of the given listener class, using the web application class loader.
*
- * @param <T> TODO
- * @param c TODO
+ * @param <T> The type of listener being created
+ * @param c The class of the listener to create
*
- * @return TODO
+ * @return The new listener instance
*
- * @throws ServletException TODO
+ * @throws ServletException If the listener cannot be instantiated, e.g., if the class does not have a
+ * no-argument constructor, or if instantiation fails for any other reason
* @throws UnsupportedOperationException If called from a
* {@link ServletContextListener#contextInitialized(ServletContextEvent)}
* method of a {@link ServletContextListener} that was not defined in a
@@ -808,9 +843,12 @@ public interface ServletContext {
<T extends EventListener> T createListener(Class<T> c) throws ServletException;
/**
- * @return TODO
+ * Returns the {@link JspConfigDescriptor} for this web application, which provides access to the JSP configuration
+ * elements such as taglib and jsp-property-group declarations.
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @return The {@link JspConfigDescriptor} for this web application
+ *
+ * @since Servlet 3.0
*/
JspConfigDescriptor getJspConfigDescriptor();
diff --git a/java/jakarta/servlet/ServletRequest.java b/java/jakarta/servlet/ServletRequest.java
index 749a9fc567..dea5715bd0 100644
--- a/java/jakarta/servlet/ServletRequest.java
+++ b/java/jakarta/servlet/ServletRequest.java
@@ -441,54 +441,66 @@ public interface ServletRequest {
int getLocalPort();
/**
- * @return TODO
+ * Returns the {@link ServletContext} to which this servlet belongs.
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @return the ServletContext associated with this request
+ *
+ * @since Servlet 3.0
*/
ServletContext getServletContext();
/**
- * @return TODO
+ * Initiates asynchronous processing for this request. The asynchronous processing is performed using the current
+ * request and response objects.
+ *
+ * @return an {@link AsyncContext} instance for managing the asynchronous processing
*
- * @throws IllegalStateException If async is not supported for this request
+ * @throws IllegalStateException if async is not supported for this request
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @since Servlet 3.0
*/
AsyncContext startAsync() throws IllegalStateException;
/**
- * @param servletRequest The ServletRequest with which to initialise the asynchronous context
- * @param servletResponse The ServletResponse with which to initialise the asynchronous context
+ * Initiates asynchronous processing for this request using the specified request and response objects.
+ *
+ * @param servletRequest the ServletRequest with which to initialise the asynchronous context
+ * @param servletResponse the ServletResponse with which to initialise the asynchronous context
*
- * @return TODO
+ * @return an {@link AsyncContext} instance for managing the asynchronous processing
*
- * @throws IllegalStateException If async is not supported for this request
+ * @throws IllegalStateException if async is not supported for this request
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @since Servlet 3.0
*/
AsyncContext startAsync(ServletRequest servletRequest, ServletResponse servletResponse)
throws IllegalStateException;
/**
- * @return TODO
+ * Returns whether asynchronous processing has been started for this request.
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @return {@code true} if asynchronous processing has been started, {@code false} otherwise
+ *
+ * @since Servlet 3.0
*/
boolean isAsyncStarted();
/**
- * @return TODO
+ * Returns whether asynchronous processing is supported for this request and has not already been started.
+ *
+ * @return {@code true} if asynchronous processing is supported and has not yet been started, {@code false}
+ * otherwise
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @since Servlet 3.0
*/
boolean isAsyncSupported();
/**
- * Get the current AsyncContext.
+ * Returns the current {@link AsyncContext} associated with this request.
*
- * @return The current AsyncContext
+ * @return the current AsyncContext
*
- * @throws IllegalStateException if the request is not in asynchronous mode (i.e. @link #isAsyncStarted() is
+ * @throws IllegalStateException if the request is not in asynchronous mode (i.e. {@link #isAsyncStarted()} is
* {@code false})
*
* @since Servlet 3.0
@@ -496,9 +508,12 @@ public interface ServletRequest {
AsyncContext getAsyncContext();
/**
- * @return TODO
+ * Returns the {@link DispatcherType} that represents the type of dispatch (REQUEST, FORWARD, INCLUDE, ERROR, or
+ * ASYNC) through which this request was initiated.
+ *
+ * @return the DispatcherType for this request
*
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * @since Servlet 3.0
*/
DispatcherType getDispatcherType();
diff --git a/java/jakarta/servlet/ServletRequestWrapper.java b/java/jakarta/servlet/ServletRequestWrapper.java
index af003a0cc7..769aa13e3e 100644
--- a/java/jakarta/servlet/ServletRequestWrapper.java
+++ b/java/jakarta/servlet/ServletRequestWrapper.java
@@ -164,7 +164,7 @@ public class ServletRequestWrapper implements ServletRequest {
* The default behavior of this method is to return getParameterMap() on the wrapped request object.
*/
@Override
- public Map<String,String[]> getParameterMap() {
+ public Map<String, String[]> getParameterMap() {
return this.request.getParameterMap();
}
@@ -400,7 +400,8 @@ public class ServletRequestWrapper implements ServletRequest {
}
/**
- * TODO SERVLET3 - Add comments
+ * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
+ * given request, then return <code>true</code>. Otherwise return <code>false</code>.
*
* @param wrapped The request to compare to the wrapped request
*
@@ -420,7 +421,8 @@ public class ServletRequestWrapper implements ServletRequest {
}
/**
- * TODO SERVLET3 - Add comments
+ * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
+ * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
*
* @param wrappedType The class to compare to the class of the wrapped request
*
diff --git a/java/jakarta/servlet/ServletResponseWrapper.java b/java/jakarta/servlet/ServletResponseWrapper.java
index 94c4e5ac01..4f9b2b5c4f 100644
--- a/java/jakarta/servlet/ServletResponseWrapper.java
+++ b/java/jakarta/servlet/ServletResponseWrapper.java
@@ -221,7 +221,8 @@ public class ServletResponseWrapper implements ServletResponse {
}
/**
- * TODO SERVLET3 - Add comments
+ * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
+ * given response, then return <code>true</code>. Otherwise return <code>false</code>.
*
* @param wrapped The response to compare to the wrapped response
*
@@ -241,7 +242,8 @@ public class ServletResponseWrapper implements ServletResponse {
}
/**
- * TODO SERVLET3 - Add comments
+ * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
+ * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
*
* @param wrappedType The class to compare to the class of the wrapped response
*
diff --git a/java/jakarta/servlet/annotation/HandlesTypes.java b/java/jakarta/servlet/annotation/HandlesTypes.java
index 7dd52b165c..203340c8b9 100644
--- a/java/jakarta/servlet/annotation/HandlesTypes.java
+++ b/java/jakarta/servlet/annotation/HandlesTypes.java
@@ -31,9 +31,11 @@ import java.lang.annotation.Target;
@Retention(RetentionPolicy.RUNTIME)
public @interface HandlesTypes {
- /**
- * @return array of classes
- */
+ /**
+ * Declares the classes handled by the {@link jakarta.servlet.ServletContainerInitializer}.
+ *
+ * @return array of classes
+ */
Class<?>[] value();
}
diff --git a/java/jakarta/servlet/annotation/MultipartConfig.java b/java/jakarta/servlet/annotation/MultipartConfig.java
index 0558b7dfd4..d0538bf954 100644
--- a/java/jakarta/servlet/annotation/MultipartConfig.java
+++ b/java/jakarta/servlet/annotation/MultipartConfig.java
@@ -41,22 +41,31 @@ import java.lang.annotation.Target;
public @interface MultipartConfig {
/**
+ * Specifies the location in which the Container stores temporary files.
+ *
* @return location in which the Container stores temporary files
*/
String location() default "";
/**
+ * Specifies the maximum size allowed for uploaded files.
+ *
* @return the maximum size allowed for uploaded files (in bytes)
*/
long maxFileSize() default -1L;
/**
+ * Specifies the maximum size of the request allowed for {@code
+ * multipart/form-data}.
+ *
* @return the maximum size of the request allowed for {@code
* multipart/form-data}
*/
long maxRequestSize() default -1L;
/**
+ * Specifies the size threshold in bytes after which the file will be written to disk.
+ *
* @return the size threshold at which the file will be written to the disk
*/
int fileSizeThreshold() default 0;
diff --git a/java/jakarta/servlet/annotation/WebFilter.java b/java/jakarta/servlet/annotation/WebFilter.java
index a277d43788..d23d9f2b0e 100644
--- a/java/jakarta/servlet/annotation/WebFilter.java
+++ b/java/jakarta/servlet/annotation/WebFilter.java
@@ -50,36 +50,50 @@ import jakarta.servlet.DispatcherType;
public @interface WebFilter {
/**
+ * Provides a description of the Filter.
+ *
* @return description of the Filter, if present
*/
String description() default "";
/**
+ * Provides a display name for the Filter.
+ *
* @return display name of the Filter, if present
*/
String displayName() default "";
/**
+ * Declares initialization parameters for the Filter.
+ *
* @return array of initialization params for this Filter
*/
WebInitParam[] initParams() default {};
/**
+ * Declares the name of the Filter.
+ *
* @return name of the Filter, if present
*/
String filterName() default "";
/**
+ * Provides a small icon for the Filter.
+ *
* @return small icon for this Filter, if present
*/
String smallIcon() default "";
/**
+ * Provides a large icon for the Filter.
+ *
* @return the large icon for this Filter, if present
*/
String largeIcon() default "";
/**
+ * Declares the servlet names to which this Filter applies.
+ *
* @return array of Servlet names to which this Filter applies
*/
String[] servletNames() default {};
@@ -94,17 +108,23 @@ public @interface WebFilter {
String[] value() default {};
/**
+ * Declares the URL patterns to which this Filter applies.
+ *
* @return array of URL patterns to which this Filter applies
*/
String[] urlPatterns() default {};
/**
+ * Declares the dispatcher types to which this Filter applies.
+ *
* @return array of DispatcherTypes to which this filter applies
*/
DispatcherType[] dispatcherTypes() default { DispatcherType.REQUEST };
/**
- * @return asynchronous operation supported by this Filter
+ * Declares whether asynchronous operation is supported by this Filter.
+ *
+ * @return {@code true} if asynchronous operation is supported, {@code false} otherwise
*/
boolean asyncSupported() default false;
}
diff --git a/java/jakarta/servlet/annotation/WebInitParam.java b/java/jakarta/servlet/annotation/WebInitParam.java
index feb4bf901b..d541fa7cff 100644
--- a/java/jakarta/servlet/annotation/WebInitParam.java
+++ b/java/jakarta/servlet/annotation/WebInitParam.java
@@ -39,16 +39,22 @@ import java.lang.annotation.Target;
public @interface WebInitParam {
/**
+ * The name of the initialization parameter.
+ *
* @return name of the initialization parameter
*/
String name();
/**
+ * The value of the initialization parameter.
+ *
* @return value of the initialization parameter
*/
String value();
/**
+ * A description of the initialization parameter.
+ *
* @return description of the initialization parameter
*/
String description() default "";
diff --git a/java/jakarta/servlet/annotation/WebListener.java b/java/jakarta/servlet/annotation/WebListener.java
index aee671b4fa..d01a2d658d 100644
--- a/java/jakarta/servlet/annotation/WebListener.java
+++ b/java/jakarta/servlet/annotation/WebListener.java
@@ -41,6 +41,8 @@ import java.lang.annotation.Target;
public @interface WebListener {
/**
+ * Provides a description of the listener.
+ *
* @return description of the listener, if present
*/
String value() default "";
diff --git a/java/jakarta/servlet/annotation/WebServlet.java b/java/jakarta/servlet/annotation/WebServlet.java
index 5e1334bd1e..ed12b5b1a3 100644
--- a/java/jakarta/servlet/annotation/WebServlet.java
+++ b/java/jakarta/servlet/annotation/WebServlet.java
@@ -46,57 +46,75 @@ import java.lang.annotation.Target;
@Documented
public @interface WebServlet {
- /**
- * @return name of the Servlet
- */
+ /**
+ * Provides the name of this servlet.
+ *
+ * @return name of the Servlet
+ */
String name() default "";
- /**
- * A convenience method, to allow extremely simple annotation of a class.
- *
- * @return array of URL patterns
- *
- * @see #urlPatterns()
- */
+ /**
+ * A convenience method, to allow extremely simple annotation of a class.
+ *
+ * @return array of URL patterns
+ *
+ * @see #urlPatterns()
+ */
String[] value() default {};
- /**
- * @return array of URL patterns to which this Filter applies
- */
+ /**
+ * Declares the URL patterns for this servlet.
+ *
+ * @return array of URL patterns to which this Servlet applies
+ */
String[] urlPatterns() default {};
- /**
- * @return load on startup ordering hint
- */
+ /**
+ * Provides a load-on-startup ordering hint for this servlet.
+ *
+ * @return load on startup ordering hint
+ */
int loadOnStartup() default -1;
- /**
- * @return array of initialization params for this Servlet
- */
+ /**
+ * Declares initialization parameters for this servlet.
+ *
+ * @return array of initialization params for this Servlet
+ */
WebInitParam[] initParams() default {};
- /**
- * @return asynchronous operation supported by this Servlet
- */
+ /**
+ * Indicates whether this servlet supports asynchronous operation.
+ *
+ * @return asynchronous operation supported by this Servlet
+ */
boolean asyncSupported() default false;
- /**
- * @return small icon for this Servlet, if present
- */
+ /**
+ * Provides the URL of a small icon for this servlet.
+ *
+ * @return small icon for this Servlet, if present
+ */
String smallIcon() default "";
- /**
- * @return large icon for this Servlet, if present
- */
+ /**
+ * Provides the URL of a large icon for this servlet.
+ *
+ * @return large icon for this Servlet, if present
+ */
String largeIcon() default "";
- /**
- * @return description of this Servlet, if present
- */
+ /**
+ * Provides a description of this servlet.
+ *
+ * @return description of this Servlet, if present
+ */
String description() default "";
- /**
- * @return display name of this Servlet, if present
- */
+ /**
+ * Provides a display name for this servlet.
+ *
+ * @return display name of this Servlet, if present
+ */
String displayName() default "";
}
diff --git a/java/jakarta/servlet/http/HttpFilter.java b/java/jakarta/servlet/http/HttpFilter.java
index a4cbf8208a..85070f9f58 100644
--- a/java/jakarta/servlet/http/HttpFilter.java
+++ b/java/jakarta/servlet/http/HttpFilter.java
@@ -34,6 +34,13 @@ public abstract class HttpFilter extends GenericFilter {
@Serial
private static final long serialVersionUID = 1L;
+ /**
+ * Constructs a new HttpFilter.
+ */
+ public HttpFilter() {
+ // NO-OP
+ }
+
/**
* {@inheritDoc} This implementation tests the request and response to see if they are instances of
* {@link HttpServletRequest} and {@link HttpServletResponse} respectively. If they are then they are passed to
diff --git a/java/jakarta/servlet/http/HttpServletMapping.java b/java/jakarta/servlet/http/HttpServletMapping.java
index ae88d321de..aece46c8e8 100644
--- a/java/jakarta/servlet/http/HttpServletMapping.java
+++ b/java/jakarta/servlet/http/HttpServletMapping.java
@@ -25,25 +25,33 @@ import jakarta.servlet.annotation.WebServlet;
*/
public interface HttpServletMapping {
- /**
- * @return The value that was matched or the empty String if not known.
- */
+ /**
+ * Returns the value that was matched when mapping the request to the servlet.
+ *
+ * @return The value that was matched or the empty String if not known.
+ */
String getMatchValue();
- /**
- * @return The {@code url-pattern} that matched this request or the empty String if not known.
- */
+ /**
+ * Returns the URL pattern that matched this request.
+ *
+ * @return The {@code url-pattern} that matched this request or the empty String if not known.
+ */
String getPattern();
- /**
- * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
- * {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
- * <code>addServlet()</code> methods) that the request was mapped to.
- */
+ /**
+ * Returns the name of the servlet to which the request was mapped.
+ *
+ * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
+ * {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
+ * <code>addServlet()</code> methods) that the request was mapped to.
+ */
String getServletName();
- /**
- * @return The type of match ({@code null} if not known)
- */
+ /**
+ * Returns the type of match used to map the request to the servlet.
+ *
+ * @return The type of match ({@code null} if not known)
+ */
MappingMatch getMappingMatch();
}
diff --git a/java/jakarta/servlet/http/PushBuilder.java b/java/jakarta/servlet/http/PushBuilder.java
index 46c6ed72bc..0adbda4a69 100644
--- a/java/jakarta/servlet/http/PushBuilder.java
+++ b/java/jakarta/servlet/http/PushBuilder.java
@@ -156,12 +156,16 @@ public interface PushBuilder {
String getSessionId();
/**
+ * Returns the set of names of HTTP headers that will be used the next time {@code push()} is called.
+ *
* @return The current set of names of HTTP headers to be used the next time {@code push()} is called.
*/
Set<String> getHeaderNames();
/**
- * Obtain a value for the given HTTP header. TODO Servlet 4.0 Clarify the behaviour of this method
+ * Obtain a value for the given HTTP header. If the push builder has not had this header set, the return value is
+ * <code>null</code>. If the push builder has had this header set multiple times, the value returned is
+ * implementation-specific.
*
* @param name The name of the header whose value is to be returned
*
diff --git a/java/jakarta/transaction/HeuristicCommitException.java b/java/jakarta/transaction/HeuristicCommitException.java
index 1c56f380d8..8f1e2e63a6 100644
--- a/java/jakarta/transaction/HeuristicCommitException.java
+++ b/java/jakarta/transaction/HeuristicCommitException.java
@@ -18,15 +18,29 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when a transaction has been heuristically committed. A heuristic
+ * commit indicates that the transaction manager has committed the transaction
+ * without full agreement from all resource managers, typically as a result of
+ * a failure during the commit process.
+ */
public class HeuristicCommitException extends Exception {
@Serial
private static final long serialVersionUID = -3977609782149921760L;
+ /**
+ * Constructs a {@code HeuristicCommitException} with no detail message.
+ */
public HeuristicCommitException() {
super();
}
+ /**
+ * Constructs a {@code HeuristicCommitException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public HeuristicCommitException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/HeuristicMixedException.java b/java/jakarta/transaction/HeuristicMixedException.java
index 50b86867a3..fbc2a93eff 100644
--- a/java/jakarta/transaction/HeuristicMixedException.java
+++ b/java/jakarta/transaction/HeuristicMixedException.java
@@ -18,15 +18,29 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when a transaction has been heuristically committed in part and
+ * heuristically rolled back in part. A heuristic mixed result indicates that
+ * some resource managers committed the transaction while others rolled it
+ * back, typically as a result of a failure during the commit process.
+ */
public class HeuristicMixedException extends Exception {
@Serial
private static final long serialVersionUID = 2345014349685956666L;
+ /**
+ * Constructs a {@code HeuristicMixedException} with no detail message.
+ */
public HeuristicMixedException() {
super();
}
+ /**
+ * Constructs a {@code HeuristicMixedException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public HeuristicMixedException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/HeuristicRollbackException.java b/java/jakarta/transaction/HeuristicRollbackException.java
index 2ee7cc6bf5..0aa897539b 100644
--- a/java/jakarta/transaction/HeuristicRollbackException.java
+++ b/java/jakarta/transaction/HeuristicRollbackException.java
@@ -18,15 +18,29 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when a transaction has been heuristically rolled back. A heuristic
+ * rollback indicates that the transaction manager has rolled back the
+ * transaction without full agreement from all resource managers, typically
+ * as a result of a failure during the commit process.
+ */
public class HeuristicRollbackException extends Exception {
@Serial
private static final long serialVersionUID = -3483618944556408897L;
+ /**
+ * Constructs a {@code HeuristicRollbackException} with no detail message.
+ */
public HeuristicRollbackException() {
super();
}
+ /**
+ * Constructs a {@code HeuristicRollbackException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public HeuristicRollbackException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/InvalidTransactionException.java b/java/jakarta/transaction/InvalidTransactionException.java
index 97e0476ab1..d8b1e12ce6 100644
--- a/java/jakarta/transaction/InvalidTransactionException.java
+++ b/java/jakarta/transaction/InvalidTransactionException.java
@@ -18,15 +18,28 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when a transaction is invalid. This exception indicates that the
+ * transaction on which an operation was attempted is no longer valid, for
+ * example because it has already completed or been rolled back.
+ */
public class InvalidTransactionException extends java.rmi.RemoteException {
@Serial
private static final long serialVersionUID = 3597320220337691496L;
+ /**
+ * Constructs an {@code InvalidTransactionException} with no detail message.
+ */
public InvalidTransactionException() {
super();
}
+ /**
+ * Constructs an {@code InvalidTransactionException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public InvalidTransactionException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/NotSupportedException.java b/java/jakarta/transaction/NotSupportedException.java
index 073ce36240..263a44f852 100644
--- a/java/jakarta/transaction/NotSupportedException.java
+++ b/java/jakarta/transaction/NotSupportedException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when a requested operation is not supported.
+ */
public class NotSupportedException extends Exception {
@Serial
private static final long serialVersionUID = 56870312332816390L;
+ /**
+ * Constructs a {@code NotSupportedException} with no detail message.
+ */
public NotSupportedException() {
super();
}
+ /**
+ * Constructs a {@code NotSupportedException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public NotSupportedException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/RollbackException.java b/java/jakarta/transaction/RollbackException.java
index f0b1d0b887..7b6beb84be 100644
--- a/java/jakarta/transaction/RollbackException.java
+++ b/java/jakarta/transaction/RollbackException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when a transaction must be rolled back.
+ */
public class RollbackException extends Exception {
@Serial
private static final long serialVersionUID = 4151607774785285395L;
+ /**
+ * Constructs a {@code RollbackException} with no detail message.
+ */
public RollbackException() {
super();
}
+ /**
+ * Constructs a {@code RollbackException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public RollbackException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/Status.java b/java/jakarta/transaction/Status.java
index 9b113fc406..d05176b77f 100644
--- a/java/jakarta/transaction/Status.java
+++ b/java/jakarta/transaction/Status.java
@@ -16,15 +16,48 @@
*/
package jakarta.transaction;
+/**
+ * Defines the set of status constants for a transaction.
+ */
public interface Status {
+ /**
+ * The transaction is active and work is in progress.
+ */
int STATUS_ACTIVE = 0;
+ /**
+ * The transaction has been marked for rollback only.
+ */
int STATUS_MARKED_ROLLBACK = 1;
+ /**
+ * The transaction resources have been prepared and are awaiting completion.
+ */
int STATUS_PREPARED = 2;
+ /**
+ * The transaction has been committed successfully.
+ */
int STATUS_COMMITTED = 3;
+ /**
+ * The transaction has been rolled back.
+ */
int STATUS_ROLLEDBACK = 4;
+ /**
+ * The transaction status is unknown.
+ */
int STATUS_UNKNOWN = 5;
+ /**
+ * There is no active transaction for the current thread.
+ */
int STATUS_NO_TRANSACTION = 6;
+ /**
+ * The transaction manager is in the process of preparing the transaction resources.
+ */
int STATUS_PREPARING = 7;
+ /**
+ * The transaction manager is in the process of committing the transaction.
+ */
int STATUS_COMMITTING = 8;
+ /**
+ * The transaction manager is in the process of rolling back the transaction.
+ */
int STATUS_ROLLING_BACK = 9;
}
diff --git a/java/jakarta/transaction/Synchronization.java b/java/jakarta/transaction/Synchronization.java
index b188911cda..c9b20d0555 100644
--- a/java/jakarta/transaction/Synchronization.java
+++ b/java/jakarta/transaction/Synchronization.java
@@ -16,8 +16,25 @@
*/
package jakarta.transaction;
+/**
+ * Callback interface for notification of transaction completion.
+ * Registered with a transaction so that the implementing object is
+ * notified when the transaction is about to complete and when it has
+ * completed.
+ */
public interface Synchronization {
+ /**
+ * Called before the transaction is committed or rolled back.
+ * This method is invoked after all work on the transaction has
+ * been completed but before the commit or rollback is performed.
+ */
void beforeCompletion();
+ /**
+ * Called after the transaction has completed.
+ *
+ * @param status the status of the transaction, one of the
+ * {@link Status} constants
+ */
void afterCompletion(int status);
}
diff --git a/java/jakarta/transaction/SystemException.java b/java/jakarta/transaction/SystemException.java
index 5c3bd33492..9b9a71d424 100644
--- a/java/jakarta/transaction/SystemException.java
+++ b/java/jakarta/transaction/SystemException.java
@@ -18,21 +18,42 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown to indicate a system error during transaction processing.
+ * When this exception is thrown, the state of the transaction is
+ * unknown and may need to be rolled back.
+ */
public class SystemException extends Exception {
@Serial
private static final long serialVersionUID = 8615483418828223571L;
+ /**
+ * The error code associated with this exception.
+ */
public int errorCode;
+ /**
+ * Constructs a {@code SystemException} with no detail message.
+ */
public SystemException() {
super();
}
+ /**
+ * Constructs a {@code SystemException} with the specified detail message.
+ *
+ * @param s the detail message
+ */
public SystemException(String s) {
super(s);
}
+ /**
+ * Constructs a {@code SystemException} with the specified error code.
+ *
+ * @param errcode the error code
+ */
public SystemException(int errcode) {
super();
errorCode = errcode;
diff --git a/java/jakarta/transaction/Transaction.java b/java/jakarta/transaction/Transaction.java
index 1f031d2a8b..626786afa8 100644
--- a/java/jakarta/transaction/Transaction.java
+++ b/java/jakarta/transaction/Transaction.java
@@ -18,21 +18,84 @@ package jakarta.transaction;
import javax.transaction.xa.XAResource;
+/**
+ * Represents an active transaction.
+ * Provides methods for committing, rolling back, and managing
+ * resources enlisted in the transaction.
+ */
public interface Transaction {
+ /**
+ * Commits the transaction.
+ *
+ * @throws RollbackException if the transaction has been marked for rollback only
+ * @throws HeuristicMixedException if the transaction was heuristically
+ * partitioned, with some resources committed and others rolled back
+ * @throws HeuristicRollbackException if the transaction was heuristically rolled back
+ * @throws SecurityException if the caller is not authorized to commit
+ * @throws IllegalStateException if the transaction is not active
+ * @throws SystemException if a system error occurred
+ */
void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
IllegalStateException, SystemException;
+ /**
+ * Delists the specified XA resource from this transaction.
+ *
+ * @param xaRes the XA resource to delist
+ * @param flag one of {@code TMSUCCESS}, {@code TMFAIL}, or {@code TMSTARTEPOCH}
+ * @return {@code true} if the resource was delisted, {@code false} otherwise
+ * @throws IllegalStateException if the transaction is not active
+ * @throws SystemException if a system error occurred
+ */
boolean delistResource(XAResource xaRes, int flag) throws IllegalStateException, SystemException;
+ /**
+ * Enlists the specified XA resource with this transaction.
+ *
+ * @param xaRes the XA resource to enlist
+ *
+ * @return {@code true} if the resource was enlisted, {@code false} otherwise
+ *
+ * @throws RollbackException if the transaction has been marked for rollback only
+ * @throws IllegalStateException if the transaction is not active or the
+ * resource is already enlisted
+ * @throws SystemException if a system error occurred
+ */
boolean enlistResource(XAResource xaRes) throws RollbackException, IllegalStateException, SystemException;
+ /**
+ * Returns the status of this transaction.
+ *
+ * @return the transaction status, one of the {@link Status} constants
+ * @throws SystemException if a system error occurred
+ */
int getStatus() throws SystemException;
+ /**
+ * Registers a synchronization callback with this transaction.
+ *
+ * @param sync the synchronization callback to register
+ * @throws RollbackException if the transaction has been marked for rollback only
+ * @throws IllegalStateException if the transaction is not active
+ * @throws SystemException if a system error occurred
+ */
void registerSynchronization(Synchronization sync) throws RollbackException, IllegalStateException, SystemException;
+ /**
+ * Rolls back the transaction.
+ *
+ * @throws IllegalStateException if the transaction is not active
+ * @throws SystemException if a system error occurred
+ */
void rollback() throws IllegalStateException, SystemException;
+ /**
+ * Marks this transaction so that the only valid outcome is a rollback.
+ *
+ * @throws IllegalStateException if the transaction is not active
+ * @throws SystemException if a system error occurred
+ */
void setRollbackOnly() throws IllegalStateException, SystemException;
}
diff --git a/java/jakarta/transaction/TransactionManager.java b/java/jakarta/transaction/TransactionManager.java
index 2bd58e16c8..633b3775ca 100644
--- a/java/jakarta/transaction/TransactionManager.java
+++ b/java/jakarta/transaction/TransactionManager.java
@@ -16,23 +16,91 @@
*/
package jakarta.transaction;
+/**
+ * Provides methods for managing transactions.
+ * Used by the transaction manager to begin, commit, and roll back
+ * transactions, and to suspend and resume them.
+ */
public interface TransactionManager {
+ /**
+ * Begins a new transaction for the current thread.
+ *
+ * @throws NotSupportedException if the transaction manager does not
+ * support transactions
+ * @throws SystemException if a system error occurred
+ */
void begin() throws NotSupportedException, SystemException;
+ /**
+ * Commits the transaction associated with the current thread.
+ *
+ * @throws RollbackException if the transaction has been marked for rollback only
+ * @throws HeuristicMixedException if the transaction was heuristically
+ * partitioned
+ * @throws HeuristicRollbackException if the transaction was heuristically rolled back
+ * @throws SecurityException if the caller is not authorized to commit
+ * @throws IllegalStateException if no transaction is active
+ * @throws SystemException if a system error occurred
+ */
void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
IllegalStateException, SystemException;
+ /**
+ * Returns the status of the transaction associated with the current thread.
+ *
+ * @return the transaction status, one of the {@link Status} constants
+ * @throws SystemException if a system error occurred
+ */
int getStatus() throws SystemException;
+ /**
+ * Returns the {@link Transaction} object associated with the current thread.
+ *
+ * @return the current transaction, or {@code null} if there is no active transaction
+ * @throws SystemException if a system error occurred
+ */
Transaction getTransaction() throws SystemException;
+ /**
+ * Resumes a previously suspended transaction for the current thread.
+ *
+ * @param tobj the transaction to resume
+ * @throws InvalidTransactionException if the transaction is no longer valid
+ * @throws IllegalStateException if there is already an active transaction
+ * @throws SystemException if a system error occurred
+ */
void resume(Transaction tobj) throws InvalidTransactionException, IllegalStateException, SystemException;
+ /**
+ * Rolls back the transaction associated with the current thread.
+ *
+ * @throws IllegalStateException if no transaction is active
+ * @throws SecurityException if the caller is not authorized to roll back
+ * @throws SystemException if a system error occurred
+ */
void rollback() throws IllegalStateException, SecurityException, SystemException;
+ /**
+ * Marks the current transaction so that the only valid outcome is a rollback.
+ *
+ * @throws IllegalStateException if no transaction is active
+ * @throws SystemException if a system error occurred
+ */
void setRollbackOnly() throws IllegalStateException, SystemException;
+ /**
+ * Sets the default transaction timeout.
+ *
+ * @param seconds the timeout value in seconds
+ * @throws SystemException if a system error occurred
+ */
void setTransactionTimeout(int seconds) throws SystemException;
+ /**
+ * Suspends the transaction associated with the current thread.
+ *
+ * @return the suspended transaction, or {@code null} if there was no active transaction
+ * @throws SystemException if a system error occurred
+ */
Transaction suspend() throws SystemException;
}
diff --git a/java/jakarta/transaction/TransactionRequiredException.java b/java/jakarta/transaction/TransactionRequiredException.java
index 32d7aef467..be6a2a6c1c 100644
--- a/java/jakarta/transaction/TransactionRequiredException.java
+++ b/java/jakarta/transaction/TransactionRequiredException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when an operation requires an active transaction but none exists.
+ */
public class TransactionRequiredException extends java.rmi.RemoteException {
@Serial
private static final long serialVersionUID = -1898806419937446439L;
+ /**
+ * Constructs a {@code TransactionRequiredException} with no detail message.
+ */
public TransactionRequiredException() {
super();
}
+ /**
+ * Constructs a {@code TransactionRequiredException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public TransactionRequiredException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/TransactionRolledbackException.java b/java/jakarta/transaction/TransactionRolledbackException.java
index 3195c429e1..12bf91627a 100644
--- a/java/jakarta/transaction/TransactionRolledbackException.java
+++ b/java/jakarta/transaction/TransactionRolledbackException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
import java.io.Serial;
+/**
+ * Thrown when an operation is attempted on a transaction that has been rolled back.
+ */
public class TransactionRolledbackException extends java.rmi.RemoteException {
@Serial
private static final long serialVersionUID = -3142798139623020577L;
+ /**
+ * Constructs a {@code TransactionRolledbackException} with no detail message.
+ */
public TransactionRolledbackException() {
super();
}
+ /**
+ * Constructs a {@code TransactionRolledbackException} with the specified detail message.
+ *
+ * @param msg the detail message
+ */
public TransactionRolledbackException(String msg) {
super(msg);
}
diff --git a/java/jakarta/transaction/TransactionSynchronizationRegistry.java b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
index b2ac98f3e2..1332cb07f0 100644
--- a/java/jakarta/transaction/TransactionSynchronizationRegistry.java
+++ b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
@@ -16,18 +16,58 @@
*/
package jakarta.transaction;
+/**
+ * Provides a resource and transaction registry for resource managers.
+ * Allows resource managers to associate resources with the current
+ * transaction and register synchronization callbacks.
+ */
public interface TransactionSynchronizationRegistry {
+ /**
+ * Returns the unique key identifying the current transaction.
+ *
+ * @return the transaction key, or {@code null} if there is no active transaction
+ */
Object getTransactionKey();
+ /**
+ * Associates a resource with the given key in the current transaction context.
+ *
+ * @param key the key to associate with the resource
+ * @param value the resource object to associate
+ */
void putResource(Object key, Object value);
+ /**
+ * Returns the resource associated with the given key in the current transaction context.
+ *
+ * @param key the key of the resource to retrieve
+ * @return the associated resource, or {@code null} if no resource is found
+ */
Object getResource(Object key);
+ /**
+ * Registers an interposed synchronization callback with the current transaction.
+ *
+ * @param sync the synchronization callback to register
+ */
void registerInterposedSynchronization(Synchronization sync);
+ /**
+ * Returns the status of the current transaction.
+ *
+ * @return the transaction status, one of the {@link Status} constants
+ */
int getTransactionStatus();
+ /**
+ * Marks the current transaction so that the only valid outcome is a rollback.
+ */
void setRollbackOnly();
+ /**
+ * Returns whether the current transaction has been marked for rollback only.
+ *
+ * @return {@code true} if the transaction is marked for rollback only
+ */
boolean getRollbackOnly();
}
diff --git a/java/jakarta/transaction/UserTransaction.java b/java/jakarta/transaction/UserTransaction.java
index 0506c9c102..04c558c0a4 100644
--- a/java/jakarta/transaction/UserTransaction.java
+++ b/java/jakarta/transaction/UserTransaction.java
@@ -16,17 +16,64 @@
*/
package jakarta.transaction;
+/**
+ * Provides methods for managing user transactions.
+ * Allows application code to demarcate transaction boundaries explicitly.
+ */
public interface UserTransaction {
+ /**
+ * Begins a new transaction for the current thread.
+ *
+ * @throws NotSupportedException if the transaction manager does not
+ * support transactions
+ * @throws SystemException if a system error occurred
+ */
void begin() throws NotSupportedException, SystemException;
+ /**
+ * Commits the transaction associated with the current thread.
+ *
+ * @throws RollbackException if the transaction has been marked for rollback only
+ * @throws HeuristicMixedException if the transaction was heuristically
+ * partitioned
+ * @throws HeuristicRollbackException if the transaction was heuristically rolled back
+ * @throws SecurityException if the caller is not authorized to commit
+ * @throws IllegalStateException if no transaction is active
+ * @throws SystemException if a system error occurred
+ */
void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
IllegalStateException, SystemException;
+ /**
+ * Rolls back the transaction associated with the current thread.
+ *
+ * @throws IllegalStateException if no transaction is active
+ * @throws SecurityException if the caller is not authorized to roll back
+ * @throws SystemException if a system error occurred
+ */
void rollback() throws IllegalStateException, SecurityException, SystemException;
+ /**
+ * Marks the current transaction so that the only valid outcome is a rollback.
+ *
+ * @throws IllegalStateException if no transaction is active
+ * @throws SystemException if a system error occurred
+ */
void setRollbackOnly() throws IllegalStateException, SystemException;
+ /**
+ * Returns the status of the transaction associated with the current thread.
+ *
+ * @return the transaction status, one of the {@link Status} constants
+ * @throws SystemException if a system error occurred
+ */
int getStatus() throws SystemException;
+ /**
+ * Sets the default transaction timeout.
+ *
+ * @param seconds the timeout value in seconds
+ * @throws SystemException if a system error occurred
+ */
void setTransactionTimeout(int seconds) throws SystemException;
}
diff --git a/java/jakarta/websocket/ClientEndpoint.java b/java/jakarta/websocket/ClientEndpoint.java
index acaa160cc8..6cfa8cbaa6 100644
--- a/java/jakarta/websocket/ClientEndpoint.java
+++ b/java/jakarta/websocket/ClientEndpoint.java
@@ -23,14 +23,39 @@ import java.lang.annotation.Target;
import jakarta.websocket.ClientEndpointConfig.Configurator;
+/**
+ * Annotates a class as a WebSocket client endpoint. The annotation provides configuration
+ * information about the endpoint such as subprotocols, encoders, decoders, and configurator.
+ */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ClientEndpoint {
+
+ /**
+ * The sub-protocols that this client endpoint supports, in order of preference.
+ *
+ * @return The list of preferred sub-protocols
+ */
String[] subprotocols() default {};
+ /**
+ * The decoder classes that this client endpoint uses.
+ *
+ * @return The list of decoder classes
+ */
Class<? extends Decoder>[] decoders() default {};
+ /**
+ * The encoder classes that this client endpoint uses.
+ *
+ * @return The list of encoder classes
+ */
Class<? extends Encoder>[] encoders() default {};
+ /**
+ * The configurator class used to customize the WebSocket handshake.
+ *
+ * @return The configurator class
+ */
Class<? extends Configurator> configurator() default Configurator.class;
}
diff --git a/java/jakarta/websocket/ClientEndpointConfig.java b/java/jakarta/websocket/ClientEndpointConfig.java
index 2af1f41575..05216b11e9 100644
--- a/java/jakarta/websocket/ClientEndpointConfig.java
+++ b/java/jakarta/websocket/ClientEndpointConfig.java
@@ -22,22 +22,53 @@ import java.util.Map;
import javax.net.ssl.SSLContext;
+/**
+ * Provides configuration information for WebSocket client endpoints.
+ */
public interface ClientEndpointConfig extends EndpointConfig {
+ /**
+ * Returns the list of sub-protocols that this client endpoint supports, in order of preference.
+ *
+ * @return The list of preferred sub-protocols
+ */
List<String> getPreferredSubprotocols();
+ /**
+ * Returns the list of extensions that this client endpoint supports.
+ *
+ * @return The list of supported extensions
+ */
List<Extension> getExtensions();
+ /**
+ * Returns the SSL context to use for secure WebSocket connections.
+ *
+ * @return The SSL context, or {@code null} if no custom SSL context is configured
+ */
SSLContext getSSLContext();
+ /**
+ * Returns the configurator used to customize the WebSocket handshake.
+ *
+ * @return The configurator for this client endpoint
+ */
Configurator getConfigurator();
+ /**
+ * Builder for creating {@link ClientEndpointConfig} instances.
+ */
final class Builder {
private static final Configurator DEFAULT_CONFIGURATOR = new Configurator() {
};
+ /**
+ * Creates a new {@link Builder} instance for building a {@link ClientEndpointConfig}.
+ *
+ * @return A new builder instance
+ */
public static Builder create() {
return new Builder();
}
@@ -54,12 +85,23 @@ public interface ClientEndpointConfig extends EndpointConfig {
private List<Class<? extends Decoder>> decoders = Collections.emptyList();
private SSLContext sslContext = null;
+ /**
+ * Builds and returns a {@link ClientEndpointConfig} with the configured settings.
+ *
+ * @return The configured client endpoint configuration
+ */
public ClientEndpointConfig build() {
return new DefaultClientEndpointConfig(preferredSubprotocols, extensions, encoders, decoders, sslContext,
configurator);
}
+ /**
+ * Sets the configurator to use for the WebSocket handshake.
+ *
+ * @param configurator The configurator, or {@code null} to use the default
+ * @return This builder instance
+ */
public Builder configurator(Configurator configurator) {
if (configurator == null) {
this.configurator = DEFAULT_CONFIGURATOR;
@@ -70,6 +112,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the list of preferred sub-protocols for the WebSocket connection.
+ *
+ * @param preferredSubprotocols The list of sub-protocols in order of preference
+ * @return This builder instance
+ */
public Builder preferredSubprotocols(List<String> preferredSubprotocols) {
if (preferredSubprotocols == null || preferredSubprotocols.isEmpty()) {
this.preferredSubprotocols = Collections.emptyList();
@@ -80,6 +128,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the list of extensions to use for the WebSocket connection.
+ *
+ * @param extensions The list of extensions
+ * @return This builder instance
+ */
public Builder extensions(List<Extension> extensions) {
if (extensions == null || extensions.isEmpty()) {
this.extensions = Collections.emptyList();
@@ -90,6 +144,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the list of encoder classes to use for the WebSocket connection.
+ *
+ * @param encoders The list of encoder classes
+ * @return This builder instance
+ */
public Builder encoders(List<Class<? extends Encoder>> encoders) {
if (encoders == null || encoders.isEmpty()) {
this.encoders = Collections.emptyList();
@@ -100,6 +160,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the list of decoder classes to use for the WebSocket connection.
+ *
+ * @param decoders The list of decoder classes
+ * @return This builder instance
+ */
public Builder decoders(List<Class<? extends Decoder>> decoders) {
if (decoders == null || decoders.isEmpty()) {
this.decoders = Collections.emptyList();
@@ -110,6 +176,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the SSL context to use for secure WebSocket connections.
+ *
+ * @param sslContext The SSL context, or {@code null} for default SSL behavior
+ * @return This builder instance
+ */
public Builder sslContext(SSLContext sslContext) {
this.sslContext = sslContext;
return this;
@@ -117,8 +189,18 @@ public interface ClientEndpointConfig extends EndpointConfig {
}
+ /**
+ * Provides a mechanism to customize the WebSocket handshake for client endpoints.
+ * Applications may subclass this to inspect or modify the handshake.
+ */
class Configurator {
+ /**
+ * Creates a new instance of the default Configurator.
+ */
+ public Configurator() {
+ }
+
/**
* Provides the client with a mechanism to inspect and/or modify the headers that are sent to the server to
* start the WebSocket handshake.
diff --git a/java/jakarta/websocket/CloseReason.java b/java/jakarta/websocket/CloseReason.java
index b7aef11305..7108dc6784 100644
--- a/java/jakarta/websocket/CloseReason.java
+++ b/java/jakarta/websocket/CloseReason.java
@@ -16,20 +16,40 @@
*/
package jakarta.websocket;
+/**
+ * Represents the reason for the closure of a WebSocket connection, including a close code
+ * and an optional reason phrase.
+ */
public class CloseReason {
private final CloseCode closeCode;
private final String reasonPhrase;
+ /**
+ * Creates a new CloseReason with the given close code and reason phrase.
+ *
+ * @param closeCode The close code
+ * @param reasonPhrase The reason phrase explaining the closure
+ */
public CloseReason(CloseReason.CloseCode closeCode, String reasonPhrase) {
this.closeCode = closeCode;
this.reasonPhrase = reasonPhrase;
}
+ /**
+ * Returns the close code.
+ *
+ * @return The close code
+ */
public CloseCode getCloseCode() {
return closeCode;
}
+ /**
+ * Returns the reason phrase.
+ *
+ * @return The reason phrase
+ */
public String getReasonPhrase() {
return reasonPhrase;
}
@@ -39,34 +59,115 @@ public class CloseReason {
return "CloseReason: code [" + closeCode.getCode() + "], reason [" + reasonPhrase + "]";
}
+ /**
+ * Represents a WebSocket close code.
+ */
public interface CloseCode {
+ /**
+ * Returns the numeric value of the close code.
+ *
+ * @return The numeric close code value
+ */
int getCode();
}
+ /**
+ * Standard WebSocket close codes as defined by RFC 6455 and related specifications.
+ */
public enum CloseCodes implements CloseReason.CloseCode {
+ /**
+ * Indicates a normal closure, meaning that the purpose for which the connection was
+ * established has been fulfilled.
+ */
NORMAL_CLOSURE(1000),
+ /**
+ * Indicates that the endpoint is going away, either because the browser is navigating
+ * away from the page, or because the server is shutting down.
+ */
GOING_AWAY(1001),
+ /**
+ * Indicates that the endpoint is terminating the connection due to a protocol error.
+ */
PROTOCOL_ERROR(1002),
+ /**
+ * Indicates that the endpoint is terminating the connection because it has received a
+ * type of data it cannot accept.
+ */
CANNOT_ACCEPT(1003),
+ /**
+ * Reserved. The specific meaning might be defined in the future.
+ */
RESERVED(1004),
+ /**
+ * Indicates that no status code was included in the closing frame. This value is
+ * reserved and must not be set as a status code in a Close control frame.
+ */
NO_STATUS_CODE(1005),
+ /**
+ * Indicates that the connection was closed abnormally without receiving a close frame.
+ * This value is reserved and must not be set as a status code in a Close control frame.
+ */
CLOSED_ABNORMALLY(1006),
+ /**
+ * Indicates that the endpoint is terminating the connection because it has received a
+ * message that contains data that is not consistent with the type of the message.
+ */
NOT_CONSISTENT(1007),
+ /**
+ * Indicates that the endpoint is terminating the connection because it has received a
+ * message that violates its policy.
+ */
VIOLATED_POLICY(1008),
+ /**
+ * Indicates that the endpoint is terminating the connection because it has received a
+ * message that is too big to process.
+ */
TOO_BIG(1009),
+ /**
+ * Indicates that the client is terminating the connection because it expected the
+ * server to negotiate one or more extension, but the server didn't return them in the
+ * handshake response.
+ */
NO_EXTENSION(1010),
+ /**
+ * Indicates that the server is terminating the connection because it encountered an
+ * unexpected condition that prevented it from fulfilling the request.
+ */
UNEXPECTED_CONDITION(1011),
+ /**
+ * Indicates that the server is restarting. A client may choose to reconnect.
+ */
SERVICE_RESTART(1012),
+ /**
+ * Indicates that the server is experiencing a temporary condition and the client should
+ * try to connect again later.
+ */
TRY_AGAIN_LATER(1013),
+ /**
+ * Indicates that the connection was closed due to a failure to perform a TLS handshake.
+ * This value is reserved and must not be set as a status code in a Close control frame.
+ */
TLS_HANDSHAKE_FAILURE(1015);
private final int code;
+ /**
+ * Creates a close code with the given numeric value.
+ *
+ * @param code The numeric close code value
+ */
CloseCodes(int code) {
this.code = code;
}
+ /**
+ * Returns the {@link CloseCode} for the given numeric code value.
+ *
+ * @param code The numeric close code value
+ * @return The corresponding {@link CloseCode}
+ * @throws IllegalArgumentException if the code is not a valid close code
+ */
public static CloseCode getCloseCode(final int code) {
if (code > 2999 && code < 5000) {
return () -> code;
@@ -91,6 +192,11 @@ public class CloseReason {
};
}
+ /**
+ * Returns the numeric value of this close code.
+ *
+ * @return The numeric close code value
+ */
@Override
public int getCode() {
return code;
diff --git a/java/jakarta/websocket/ContainerProvider.java b/java/jakarta/websocket/ContainerProvider.java
index 56381d0dde..f79f7f8ed3 100644
--- a/java/jakarta/websocket/ContainerProvider.java
+++ b/java/jakarta/websocket/ContainerProvider.java
@@ -24,6 +24,12 @@ import java.util.ServiceLoader;
*/
public abstract class ContainerProvider {
+ /**
+ * Creates a new ContainerProvider instance.
+ */
+ protected ContainerProvider() {
+ }
+
private static final String DEFAULT_PROVIDER_CLASS_NAME = "org.apache.tomcat.websocket.WsWebSocketContainer";
/**
@@ -54,5 +60,10 @@ public abstract class ContainerProvider {
return result;
}
+ /**
+ * Returns the WebSocket container provided by this provider.
+ *
+ * @return The WebSocket container
+ */
protected abstract WebSocketContainer getContainer();
}
diff --git a/java/jakarta/websocket/DecodeException.java b/java/jakarta/websocket/DecodeException.java
index e6a9279094..d40fb4870f 100644
--- a/java/jakarta/websocket/DecodeException.java
+++ b/java/jakarta/websocket/DecodeException.java
@@ -19,38 +19,83 @@ package jakarta.websocket;
import java.io.Serial;
import java.nio.ByteBuffer;
+/**
+ * Exception thrown when a decoder fails to decode a WebSocket message.
+ */
public class DecodeException extends Exception {
@Serial
private static final long serialVersionUID = 1L;
+ /**
+ * The binary data that could not be decoded.
+ */
private ByteBuffer bb;
+ /**
+ * The text data that could not be decoded.
+ */
private String encodedString;
+ /**
+ * Creates a DecodeException for binary data with the specified detail message and cause.
+ *
+ * @param bb The binary data that could not be decoded
+ * @param message The detail message
+ * @param cause The underlying cause of the exception
+ */
public DecodeException(ByteBuffer bb, String message, Throwable cause) {
super(message, cause);
this.bb = bb;
}
+ /**
+ * Creates a DecodeException for text data with the specified detail message and cause.
+ *
+ * @param encodedString The text data that could not be decoded
+ * @param message The detail message
+ * @param cause The underlying cause of the exception
+ */
public DecodeException(String encodedString, String message, Throwable cause) {
super(message, cause);
this.encodedString = encodedString;
}
+ /**
+ * Creates a DecodeException for binary data with the specified detail message.
+ *
+ * @param bb The binary data that could not be decoded
+ * @param message The detail message
+ */
public DecodeException(ByteBuffer bb, String message) {
super(message);
this.bb = bb;
}
+ /**
+ * Creates a DecodeException for text data with the specified detail message.
+ *
+ * @param encodedString The text data that could not be decoded
+ * @param message The detail message
+ */
public DecodeException(String encodedString, String message) {
super(message);
this.encodedString = encodedString;
}
+ /**
+ * Returns the binary data that could not be decoded.
+ *
+ * @return The binary data, or {@code null} if the exception was for text data
+ */
public ByteBuffer getBytes() {
return bb;
}
+ /**
+ * Returns the text data that could not be decoded.
+ *
+ * @return The text data, or {@code null} if the exception was for binary data
+ */
public String getText() {
return encodedString;
}
diff --git a/java/jakarta/websocket/Decoder.java b/java/jakarta/websocket/Decoder.java
index 4f0a4e4c04..03db069e6a 100644
--- a/java/jakarta/websocket/Decoder.java
+++ b/java/jakarta/websocket/Decoder.java
@@ -21,6 +21,10 @@ import java.io.InputStream;
import java.io.Reader;
import java.nio.ByteBuffer;
+/**
+ * Base interface for WebSocket message decoders. Decoders convert incoming WebSocket messages
+ * from their raw form (text or binary) into application-specific objects.
+ */
public interface Decoder {
/**
@@ -37,27 +41,91 @@ public interface Decoder {
default void destroy() {
}
+ /**
+ * A decoder that decodes entire binary WebSocket messages into an object of type T.
+ *
+ * @param <T> The type of object produced by the decoder
+ */
interface Binary<T> extends Decoder {
+ /**
+ * Decodes the binary data into an object.
+ *
+ * @param bytes The binary data to decode
+ * @return The decoded object
+ * @throws DecodeException If the data cannot be decoded
+ */
T decode(ByteBuffer bytes) throws DecodeException;
+ /**
+ * Determines whether this decoder can decode the given binary data.
+ *
+ * @param bytes The binary data to check
+ * @return {@code true} if this decoder can decode the data
+ */
boolean willDecode(ByteBuffer bytes);
}
+ /**
+ * A decoder that decodes entire binary WebSocket messages from an input stream into an
+ * object of type T.
+ *
+ * @param <T> The type of object produced by the decoder
+ */
interface BinaryStream<T> extends Decoder {
+ /**
+ * Decodes the binary data from the input stream into an object.
+ *
+ * @param is The input stream containing the binary data
+ * @return The decoded object
+ * @throws DecodeException If the data cannot be decoded
+ * @throws IOException If an I/O error occurs
+ */
T decode(InputStream is) throws DecodeException, IOException;
}
+ /**
+ * A decoder that decodes entire text WebSocket messages into an object of type T.
+ *
+ * @param <T> The type of object produced by the decoder
+ */
interface Text<T> extends Decoder {
+ /**
+ * Decodes the text data into an object.
+ *
+ * @param s The text data to decode
+ * @return The decoded object
+ * @throws DecodeException If the data cannot be decoded
+ */
T decode(String s) throws DecodeException;
+ /**
+ * Determines whether this decoder can decode the given text data.
+ *
+ * @param s The text data to check
+ * @return {@code true} if this decoder can decode the data
+ */
boolean willDecode(String s);
}
+ /**
+ * A decoder that decodes entire text WebSocket messages from a reader into an object of
+ * type T.
+ *
+ * @param <T> The type of object produced by the decoder
+ */
interface TextStream<T> extends Decoder {
+ /**
+ * Decodes the text data from the reader into an object.
+ *
+ * @param reader The reader containing the text data
+ * @return The decoded object
+ * @throws DecodeException If the data cannot be decoded
+ * @throws IOException If an I/O error occurs
+ */
T decode(Reader reader) throws DecodeException, IOException;
}
}
diff --git a/java/jakarta/websocket/DeploymentException.java b/java/jakarta/websocket/DeploymentException.java
index d12f62680b..1bc0202cbd 100644
--- a/java/jakarta/websocket/DeploymentException.java
+++ b/java/jakarta/websocket/DeploymentException.java
@@ -18,15 +18,29 @@ package jakarta.websocket;
import java.io.Serial;
+/**
+ * Exception thrown when a WebSocket endpoint cannot be deployed due to a configuration error.
+ */
public class DeploymentException extends Exception {
@Serial
private static final long serialVersionUID = 1L;
+ /**
+ * Creates a DeploymentException with the specified detail message.
+ *
+ * @param message The detail message
+ */
public DeploymentException(String message) {
super(message);
}
+ /**
+ * Creates a DeploymentException with the specified detail message and cause.
+ *
+ * @param message The detail message
+ * @param cause The underlying cause of the exception
+ */
public DeploymentException(String message, Throwable cause) {
super(message, cause);
}
diff --git a/java/jakarta/websocket/EncodeException.java b/java/jakarta/websocket/EncodeException.java
index 406b0ffee1..86b78c29d1 100644
--- a/java/jakarta/websocket/EncodeException.java
+++ b/java/jakarta/websocket/EncodeException.java
@@ -18,23 +18,47 @@ package jakarta.websocket;
import java.io.Serial;
+/**
+ * Exception thrown when an encoder fails to encode an object as a WebSocket message.
+ */
public class EncodeException extends Exception {
@Serial
private static final long serialVersionUID = 1L;
+ /**
+ * The object that could not be encoded.
+ */
private final Object object;
+ /**
+ * Creates an EncodeException with the specified object and detail message.
+ *
+ * @param object The object that could not be encoded
+ * @param message The detail message
+ */
public EncodeException(Object object, String message) {
super(message);
this.object = object;
}
+ /**
+ * Creates an EncodeException with the specified object, detail message, and cause.
+ *
+ * @param object The object that could not be encoded
+ * @param message The detail message
+ * @param cause The underlying cause of the exception
+ */
public EncodeException(Object object, String message, Throwable cause) {
super(message, cause);
this.object = object;
}
+ /**
+ * Returns the object that could not be encoded.
+ *
+ * @return The object that could not be encoded
+ */
public Object getObject() {
return this.object;
}
diff --git a/java/jakarta/websocket/Encoder.java b/java/jakarta/websocket/Encoder.java
index 808cf3d79b..a1268268dd 100644
--- a/java/jakarta/websocket/Encoder.java
+++ b/java/jakarta/websocket/Encoder.java
@@ -21,6 +21,10 @@ import java.io.OutputStream;
import java.io.Writer;
import java.nio.ByteBuffer;
+/**
+ * Base interface for WebSocket message encoders. Encoders convert application-specific objects
+ * into WebSocket messages in text or binary form.
+ */
public interface Encoder {
/**
@@ -32,28 +36,80 @@ public interface Encoder {
}
/**
- * Destroy the decoder. The default implementation is a NO-OP.
+ * Destroy the encoder. The default implementation is a NO-OP.
*/
default void destroy() {
}
+ /**
+ * An encoder that encodes an object of type T into a text WebSocket message.
+ *
+ * @param <T> The type of object accepted by the encoder
+ */
interface Text<T> extends Encoder {
+ /**
+ * Encodes the given object into a text string.
+ *
+ * @param object The object to encode
+ * @return The encoded text string
+ * @throws EncodeException If the object cannot be encoded
+ */
String encode(T object) throws EncodeException;
}
+ /**
+ * An encoder that encodes an object of type T into a text WebSocket message written to
+ * a {@link Writer}.
+ *
+ * @param <T> The type of object accepted by the encoder
+ */
interface TextStream<T> extends Encoder {
+ /**
+ * Encodes the given object and writes the result to the writer.
+ *
+ * @param object The object to encode
+ * @param writer The writer to write the encoded data to
+ * @throws EncodeException If the object cannot be encoded
+ * @throws IOException If an I/O error occurs
+ */
void encode(T object, Writer writer) throws EncodeException, IOException;
}
+ /**
+ * An encoder that encodes an object of type T into a binary WebSocket message.
+ *
+ * @param <T> The type of object accepted by the encoder
+ */
interface Binary<T> extends Encoder {
+ /**
+ * Encodes the given object into a ByteBuffer.
+ *
+ * @param object The object to encode
+ * @return The encoded binary data
+ * @throws EncodeException If the object cannot be encoded
+ */
ByteBuffer encode(T object) throws EncodeException;
}
+ /**
+ * An encoder that encodes an object of type T into a binary WebSocket message written to
+ * an {@link OutputStream}.
+ *
+ * @param <T> The type of object accepted by the encoder
+ */
interface BinaryStream<T> extends Encoder {
+ /**
+ * Encodes the given object and writes the result to the output stream.
+ *
+ * @param object The object to encode
+ * @param os The output stream to write the encoded data to
+ * @throws EncodeException If the object cannot be encoded
+ * @throws IOException If an I/O error occurs
+ */
void encode(T object, OutputStream os) throws EncodeException, IOException;
}
}
diff --git a/java/jakarta/websocket/Endpoint.java b/java/jakarta/websocket/Endpoint.java
index 059430d25e..a832ac9538 100644
--- a/java/jakarta/websocket/Endpoint.java
+++ b/java/jakarta/websocket/Endpoint.java
@@ -16,8 +16,18 @@
*/
package jakarta.websocket;
+/**
+ * Base class for programmatic WebSocket endpoints. Subclasses must implement the
+ * {@link #onOpen(Session, EndpointConfig)} method to handle new connections.
+ */
public abstract class Endpoint {
+ /**
+ * Creates a new Endpoint instance.
+ */
+ public Endpoint() {
+ }
+
/**
* Event that is triggered when a new session starts.
*
diff --git a/java/jakarta/websocket/EndpointConfig.java b/java/jakarta/websocket/EndpointConfig.java
index ed2d423610..7e85ca55c0 100644
--- a/java/jakarta/websocket/EndpointConfig.java
+++ b/java/jakarta/websocket/EndpointConfig.java
@@ -19,11 +19,30 @@ package jakarta.websocket;
import java.util.List;
import java.util.Map;
+/**
+ * Provides configuration information for a WebSocket endpoint, including encoders, decoders,
+ * and user properties.
+ */
public interface EndpointConfig {
+ /**
+ * Returns the list of encoder classes for this endpoint.
+ *
+ * @return The list of encoder classes
+ */
List<Class<? extends Encoder>> getEncoders();
+ /**
+ * Returns the list of decoder classes for this endpoint.
+ *
+ * @return The list of decoder classes
+ */
List<Class<? extends Decoder>> getDecoders();
+ /**
+ * Returns a map of user properties associated with this endpoint configuration.
+ *
+ * @return The user properties map
+ */
Map<String,Object> getUserProperties();
}
diff --git a/java/jakarta/websocket/Extension.java b/java/jakarta/websocket/Extension.java
index a4cbca8f62..61a261c307 100644
--- a/java/jakarta/websocket/Extension.java
+++ b/java/jakarta/websocket/Extension.java
@@ -18,14 +18,42 @@ package jakarta.websocket;
import java.util.List;
+/**
+ * Represents a WebSocket extension that can be negotiated during the handshake.
+ */
public interface Extension {
+
+ /**
+ * Returns the name of this extension.
+ *
+ * @return The extension name
+ */
String getName();
+ /**
+ * Returns the parameters associated with this extension.
+ *
+ * @return The list of extension parameters
+ */
List<Parameter> getParameters();
+ /**
+ * Represents a parameter of a WebSocket extension.
+ */
interface Parameter {
+
+ /**
+ * Returns the name of this parameter.
+ *
+ * @return The parameter name
+ */
String getName();
+ /**
+ * Returns the value of this parameter.
+ *
+ * @return The parameter value
+ */
String getValue();
}
}
diff --git a/java/jakarta/websocket/HandshakeResponse.java b/java/jakarta/websocket/HandshakeResponse.java
index e5faf9d801..900551f880 100644
--- a/java/jakarta/websocket/HandshakeResponse.java
+++ b/java/jakarta/websocket/HandshakeResponse.java
@@ -19,6 +19,9 @@ package jakarta.websocket;
import java.util.List;
import java.util.Map;
+/**
+ * Represents the HTTP response returned by the server during a WebSocket handshake.
+ */
public interface HandshakeResponse {
/**
@@ -26,5 +29,10 @@ public interface HandshakeResponse {
*/
String SEC_WEBSOCKET_ACCEPT = "Sec-WebSocket-Accept";
+ /**
+ * Returns the HTTP headers from the handshake response.
+ *
+ * @return The HTTP headers
+ */
Map<String,List<String>> getHeaders();
}
diff --git a/java/jakarta/websocket/MessageHandler.java b/java/jakarta/websocket/MessageHandler.java
index 748dd76776..ace7c96702 100644
--- a/java/jakarta/websocket/MessageHandler.java
+++ b/java/jakarta/websocket/MessageHandler.java
@@ -16,8 +16,18 @@
*/
package jakarta.websocket;
+/**
+ * Base interface for WebSocket message handlers. Use {@link Whole} for handling complete
+ * messages and {@link Partial} for handling messages that may arrive in fragments.
+ */
public interface MessageHandler {
+ /**
+ * A message handler that receives partial (fragmented) messages. The handler is called
+ * multiple times for a single WebSocket message if it arrives in fragments.
+ *
+ * @param <T> The type of message data
+ */
interface Partial<T> extends MessageHandler {
/**
@@ -29,6 +39,12 @@ public interface MessageHandler {
void onMessage(T messagePart, boolean last);
}
+ /**
+ * A message handler that receives whole (complete) messages. The handler is called once
+ * per WebSocket message.
+ *
+ * @param <T> The type of message data
+ */
interface Whole<T> extends MessageHandler {
/**
diff --git a/java/jakarta/websocket/OnClose.java b/java/jakarta/websocket/OnClose.java
index 31291165bc..8c071d1f85 100644
--- a/java/jakarta/websocket/OnClose.java
+++ b/java/jakarta/websocket/OnClose.java
@@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Annotates a method on a POJO endpoint to handle the close event. The annotated method
+ * will be called when the WebSocket session is closed.
+ */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface OnClose {
diff --git a/java/jakarta/websocket/OnError.java b/java/jakarta/websocket/OnError.java
index a09a5bde28..cba6abd9ac 100644
--- a/java/jakarta/websocket/OnError.java
+++ b/java/jakarta/websocket/OnError.java
@@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Annotates a method on a POJO endpoint to handle error events. The annotated method
+ * will be called when an error occurs on the WebSocket session.
+ */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface OnError {
diff --git a/java/jakarta/websocket/OnMessage.java b/java/jakarta/websocket/OnMessage.java
index 34cfcfa18e..49d95b8c74 100644
--- a/java/jakarta/websocket/OnMessage.java
+++ b/java/jakarta/websocket/OnMessage.java
@@ -21,8 +21,19 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Annotates a method on a POJO endpoint to handle incoming WebSocket messages. The annotated
+ * method will be called when a message is received.
+ */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface OnMessage {
+
+ /**
+ * The maximum message size in bytes that this handler will accept. Messages larger than
+ * this size will be discarded. A value of -1 indicates no limit.
+ *
+ * @return The maximum message size in bytes
+ */
long maxMessageSize() default -1;
}
diff --git a/java/jakarta/websocket/OnOpen.java b/java/jakarta/websocket/OnOpen.java
index 26b8e9d1e0..48f98d7bbd 100644
--- a/java/jakarta/websocket/OnOpen.java
+++ b/java/jakarta/websocket/OnOpen.java
@@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Annotates a method on a POJO endpoint to handle the open event. The annotated method
+ * will be called when a new WebSocket session is established.
+ */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface OnOpen {
diff --git a/java/jakarta/websocket/RemoteEndpoint.java b/java/jakarta/websocket/RemoteEndpoint.java
index 9826d98cc0..a485581c65 100644
--- a/java/jakarta/websocket/RemoteEndpoint.java
+++ b/java/jakarta/websocket/RemoteEndpoint.java
@@ -23,8 +23,15 @@ import java.nio.ByteBuffer;
import java.util.concurrent.Future;
+/**
+ * Interface for sending messages to the remote endpoint of a WebSocket session.
+ * Provides both synchronous ({@link Basic}) and asynchronous ({@link Async}) sending capabilities.
+ */
public interface RemoteEndpoint {
+ /**
+ * Asynchronous API for sending messages to the remote endpoint.
+ */
interface Async extends RemoteEndpoint {
/**
@@ -109,6 +116,9 @@ public interface RemoteEndpoint {
}
+ /**
+ * Synchronous (blocking) API for sending messages to the remote endpoint.
+ */
interface Basic extends RemoteEndpoint {
/**
@@ -155,8 +165,20 @@ public interface RemoteEndpoint {
*/
void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException;
+ /**
+ * Returns an {@link OutputStream} for sending a binary message to the remote endpoint.
+ *
+ * @return An output stream for sending binary data
+ * @throws IOException if an I/O error occurs
+ */
OutputStream getSendStream() throws IOException;
+ /**
+ * Returns a {@link Writer} for sending a text message to the remote endpoint.
+ *
+ * @return A writer for sending text data
+ * @throws IOException if an I/O error occurs
+ */
Writer getSendWriter() throws IOException;
/**
diff --git a/java/jakarta/websocket/SendHandler.java b/java/jakarta/websocket/SendHandler.java
index 9e8317c5b5..ee34f7a25c 100644
--- a/java/jakarta/websocket/SendHandler.java
+++ b/java/jakarta/websocket/SendHandler.java
@@ -16,7 +16,15 @@
*/
package jakarta.websocket;
+/**
+ * Callback interface for handling the result of an asynchronous WebSocket message send operation.
+ */
public interface SendHandler {
+ /**
+ * Called when the asynchronous send operation completes.
+ *
+ * @param result The result of the send operation
+ */
void onResult(SendResult result);
}
diff --git a/java/jakarta/websocket/SendResult.java b/java/jakarta/websocket/SendResult.java
index f506c881af..b7a6842f37 100644
--- a/java/jakarta/websocket/SendResult.java
+++ b/java/jakarta/websocket/SendResult.java
@@ -16,6 +16,9 @@
*/
package jakarta.websocket;
+/**
+ * Represents the result of an asynchronous WebSocket message send operation.
+ */
public final class SendResult {
private final Session session;
private final Throwable exception;
@@ -66,10 +69,21 @@ public final class SendResult {
this(null, null);
}
+ /**
+ * Returns the exception that occurred during the send operation, or {@code null} if the
+ * operation was successful.
+ *
+ * @return The exception, or {@code null} if successful
+ */
public Throwable getException() {
return exception;
}
+ /**
+ * Returns whether the send operation was successful.
+ *
+ * @return {@code true} if the send was successful, {@code false} otherwise
+ */
public boolean isOK() {
return ok;
}
diff --git a/java/jakarta/websocket/Session.java b/java/jakarta/websocket/Session.java
index 21e20ea086..eb439795a4 100644
--- a/java/jakarta/websocket/Session.java
+++ b/java/jakarta/websocket/Session.java
@@ -24,6 +24,11 @@ import java.util.List;
import java.util.Map;
import java.util.Set;
+/**
+ * Represents a WebSocket session, which is the WebSocket connection between a client and a server.
+ * A session is created when a WebSocket connection is established and is used to send and receive
+ * messages.
+ */
public interface Session extends Closeable {
/**
@@ -46,18 +51,54 @@ public interface Session extends Closeable {
*/
void addMessageHandler(MessageHandler handler) throws IllegalStateException;
+ /**
+ * Returns the set of message handlers currently registered on this session.
+ *
+ * @return The set of registered message handlers
+ */
Set<MessageHandler> getMessageHandlers();
+ /**
+ * Removes the specified message handler from this session.
+ *
+ * @param listener The message handler to remove
+ */
void removeMessageHandler(MessageHandler listener);
+ /**
+ * Returns the version of the WebSocket protocol in use for this session.
+ *
+ * @return The protocol version
+ */
String getProtocolVersion();
+ /**
+ * Returns the sub-protocol negotiated for this session, or {@code null} if no sub-protocol
+ * was negotiated.
+ *
+ * @return The negotiated sub-protocol
+ */
String getNegotiatedSubprotocol();
+ /**
+ * Returns the list of extensions negotiated for this session.
+ *
+ * @return The list of negotiated extensions
+ */
List<Extension> getNegotiatedExtensions();
+ /**
+ * Returns whether this session is using a secure connection (wss://).
+ *
+ * @return {@code true} if the connection is secure
+ */
boolean isSecure();
+ /**
+ * Returns whether this session is currently open.
+ *
+ * @return {@code true} if the session is open
+ */
boolean isOpen();
/**
@@ -104,8 +145,19 @@ public interface Session extends Closeable {
*/
int getMaxTextMessageBufferSize();
+ /**
+ * Returns the asynchronous remote endpoint for this session, used for non-blocking message
+ * sending.
+ *
+ * @return The asynchronous remote endpoint
+ */
RemoteEndpoint.Async getAsyncRemote();
+ /**
+ * Returns the synchronous remote endpoint for this session, used for blocking message sending.
+ *
+ * @return The synchronous remote endpoint
+ */
RemoteEndpoint.Basic getBasicRemote();
/**
@@ -135,16 +187,47 @@ public interface Session extends Closeable {
*/
void close(CloseReason closeReason) throws IOException;
+ /**
+ * Returns the URI of the request that initiated this WebSocket session.
+ *
+ * @return The request URI
+ */
URI getRequestURI();
+ /**
+ * Returns the query parameters from the request that initiated this WebSocket session.
+ *
+ * @return The query parameter map
+ */
Map<String,List<String>> getRequestParameterMap();
+ /**
+ * Returns the query string from the request that initiated this WebSocket session.
+ *
+ * @return The query string
+ */
String getQueryString();
+ /**
+ * Returns the path parameters extracted from the request URI using the endpoint's URI template.
+ *
+ * @return The path parameter map
+ */
Map<String,String> getPathParameters();
+ /**
+ * Returns a map of user properties associated with this session.
+ *
+ * @return The user properties map
+ */
Map<String,Object> getUserProperties();
+ /**
+ * Returns the principal of the user associated with this session, or {@code null} if the
+ * user is not authenticated.
+ *
+ * @return The user principal
+ */
Principal getUserPrincipal();
/**
diff --git a/java/jakarta/websocket/SessionException.java b/java/jakarta/websocket/SessionException.java
index d1d0f9908c..7645c73fa0 100644
--- a/java/jakarta/websocket/SessionException.java
+++ b/java/jakarta/websocket/SessionException.java
@@ -18,20 +18,38 @@ package jakarta.websocket;
import java.io.Serial;
+/**
+ * Exception thrown when an error occurs on a WebSocket session.
+ */
public class SessionException extends Exception {
@Serial
private static final long serialVersionUID = 1L;
+ /**
+ * The session on which the error occurred.
+ */
private final Session session;
+ /**
+ * Creates a SessionException with the specified detail message, cause, and session.
+ *
+ * @param message The detail message
+ * @param cause The underlying cause of the exception
+ * @param session The session on which the error occurred
+ */
public SessionException(String message, Throwable cause, Session session) {
super(message, cause);
this.session = session;
}
+ /**
+ * Returns the session on which the error occurred.
+ *
+ * @return The session
+ */
public Session getSession() {
return session;
}
diff --git a/java/jakarta/websocket/WebSocketContainer.java b/java/jakarta/websocket/WebSocketContainer.java
index 82ddb7ff47..7613ece7a7 100644
--- a/java/jakarta/websocket/WebSocketContainer.java
+++ b/java/jakarta/websocket/WebSocketContainer.java
@@ -20,6 +20,9 @@ import java.io.IOException;
import java.net.URI;
import java.util.Set;
+/**
+ * Provides the ability to create new WebSocket client connections.
+ */
public interface WebSocketContainer {
/**
@@ -36,8 +39,27 @@ public interface WebSocketContainer {
*/
void setAsyncSendTimeout(long timeout);
+ /**
+ * Creates a new connection to the WebSocket server endpoint.
+ *
+ * @param endpoint The POJO endpoint instance that will handle responses from the server
+ * @param path The full URL of the WebSocket endpoint to connect to
+ * @return The WebSocket session for the connection
+ * @throws DeploymentException If the connection cannot be established
+ * @throws IOException If an I/O error occurred while trying to establish the connection
+ */
Session connectToServer(Object endpoint, URI path) throws DeploymentException, IOException;
+ /**
+ * Creates a new connection to the WebSocket server endpoint.
+ *
+ * @param annotatedEndpointClass The annotated endpoint class. An instance of this class will be
+ * created to handle responses from the server
+ * @param path The full URL of the WebSocket endpoint to connect to
+ * @return The WebSocket session for the connection
+ * @throws DeploymentException If the connection cannot be established
+ * @throws IOException If an I/O error occurred while trying to establish the connection
+ */
Session connectToServer(Class<?> annotatedEndpointClass, URI path) throws DeploymentException, IOException;
/**
diff --git a/java/jakarta/websocket/server/HandshakeRequest.java b/java/jakarta/websocket/server/HandshakeRequest.java
index 457942ed76..a17cb21545 100644
--- a/java/jakarta/websocket/server/HandshakeRequest.java
+++ b/java/jakarta/websocket/server/HandshakeRequest.java
@@ -26,17 +26,51 @@ import java.util.Map;
*/
public interface HandshakeRequest {
+ /**
+ * Name of the Sec-WebSocket-Key HTTP header.
+ */
String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key";
+ /**
+ * Name of the Sec-WebSocket-Protocol HTTP header.
+ */
String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol";
+ /**
+ * Name of the Sec-WebSocket-Version HTTP header.
+ */
String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version";
+ /**
+ * Name of the Sec-WebSocket-Extensions HTTP header.
+ */
String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions";
+ /**
+ * Returns the HTTP headers from the handshake request.
+ *
+ * @return The HTTP headers
+ */
Map<String,List<String>> getHeaders();
+ /**
+ * Returns the principal of the user associated with this request, or {@code null} if the
+ * user is not authenticated.
+ *
+ * @return The user principal
+ */
Principal getUserPrincipal();
+ /**
+ * Returns the URI of the handshake request.
+ *
+ * @return The request URI
+ */
URI getRequestURI();
+ /**
+ * Returns whether the user associated with this request is in the given role.
+ *
+ * @param role The role to check
+ * @return {@code true} if the user is in the specified role
+ */
boolean isUserInRole(String role);
/**
@@ -47,7 +81,17 @@ public interface HandshakeRequest {
*/
Object getHttpSession();
+ /**
+ * Returns the query parameters from the handshake request.
+ *
+ * @return The query parameter map
+ */
Map<String,List<String>> getParameterMap();
+ /**
+ * Returns the query string from the handshake request.
+ *
+ * @return The query string
+ */
String getQueryString();
}
diff --git a/java/jakarta/websocket/server/PathParam.java b/java/jakarta/websocket/server/PathParam.java
index 22293b3dda..b86dbbf85b 100644
--- a/java/jakarta/websocket/server/PathParam.java
+++ b/java/jakarta/websocket/server/PathParam.java
@@ -28,5 +28,11 @@ import java.lang.annotation.Target;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
public @interface PathParam {
+
+ /**
+ * The name of the path parameter from the URI template.
+ *
+ * @return The path parameter name
+ */
String value();
}
diff --git a/java/jakarta/websocket/server/ServerContainer.java b/java/jakarta/websocket/server/ServerContainer.java
index 82b92dc7bd..e6c4f68c91 100644
--- a/java/jakarta/websocket/server/ServerContainer.java
+++ b/java/jakarta/websocket/server/ServerContainer.java
@@ -26,8 +26,21 @@ import jakarta.websocket.WebSocketContainer;
* Provides the ability to deploy endpoints programmatically.
*/
public interface ServerContainer extends WebSocketContainer {
+ /**
+ * Deploys the given endpoint class. The class must be annotated with
+ * {@link jakarta.websocket.server.ServerEndpoint} or extend {@link jakarta.websocket.Endpoint}.
+ *
+ * @param clazz The endpoint class to deploy
+ * @throws DeploymentException If the endpoint cannot be deployed
+ */
void addEndpoint(Class<?> clazz) throws DeploymentException;
+ /**
+ * Deploys the endpoint configured by the given {@link ServerEndpointConfig}.
+ *
+ * @param sec The server endpoint configuration
+ * @throws DeploymentException If the endpoint cannot be deployed
+ */
void addEndpoint(ServerEndpointConfig sec) throws DeploymentException;
/**
diff --git a/java/jakarta/websocket/server/ServerEndpoint.java b/java/jakarta/websocket/server/ServerEndpoint.java
index b29ebec134..f0efc31112 100644
--- a/java/jakarta/websocket/server/ServerEndpoint.java
+++ b/java/jakarta/websocket/server/ServerEndpoint.java
@@ -24,6 +24,11 @@ import java.lang.annotation.Target;
import jakarta.websocket.Decoder;
import jakarta.websocket.Encoder;
+/**
+ * Annotates a class as a WebSocket server endpoint. The annotation provides configuration
+ * information about the endpoint such as the URI path, subprotocols, encoders, decoders,
+ * and configurator.
+ */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ServerEndpoint {
@@ -35,11 +40,31 @@ public @interface ServerEndpoint {
*/
String value();
+ /**
+ * The sub-protocols that this server endpoint supports.
+ *
+ * @return The list of supported sub-protocols
+ */
String[] subprotocols() default {};
+ /**
+ * The decoder classes that this server endpoint uses.
+ *
+ * @return The list of decoder classes
+ */
Class<? extends Decoder>[] decoders() default {};
+ /**
+ * The encoder classes that this server endpoint uses.
+ *
+ * @return The list of encoder classes
+ */
Class<? extends Encoder>[] encoders() default {};
+ /**
+ * The configurator class used to customize the WebSocket handshake.
+ *
+ * @return The configurator class
+ */
Class<? extends ServerEndpointConfig.Configurator> configurator() default ServerEndpointConfig.Configurator.class;
}
diff --git a/java/jakarta/websocket/server/ServerEndpointConfig.java b/java/jakarta/websocket/server/ServerEndpointConfig.java
index e72a879608..caf697a61b 100644
--- a/java/jakarta/websocket/server/ServerEndpointConfig.java
+++ b/java/jakarta/websocket/server/ServerEndpointConfig.java
@@ -33,6 +33,11 @@ import jakarta.websocket.HandshakeResponse;
*/
public interface ServerEndpointConfig extends EndpointConfig {
+ /**
+ * Returns the class of the endpoint.
+ *
+ * @return The endpoint class
+ */
Class<?> getEndpointClass();
/**
@@ -43,15 +48,40 @@ public interface ServerEndpointConfig extends EndpointConfig {
*/
String getPath();
+ /**
+ * Returns the list of sub-protocols supported by this endpoint.
+ *
+ * @return The list of supported sub-protocols
+ */
List<String> getSubprotocols();
+ /**
+ * Returns the list of extensions supported by this endpoint.
+ *
+ * @return The list of supported extensions
+ */
List<Extension> getExtensions();
+ /**
+ * Returns the configurator for this server endpoint.
+ *
+ * @return The configurator
+ */
Configurator getConfigurator();
+ /**
+ * Builder for creating {@link ServerEndpointConfig} instances.
+ */
final class Builder {
+ /**
+ * Creates a new builder for the given endpoint class and path.
+ *
+ * @param endpointClass The endpoint class
+ * @param path The path at which the endpoint will be registered
+ * @return A new builder instance
+ */
public static Builder create(Class<?> endpointClass, String path) {
return new Builder(endpointClass, path);
}
@@ -83,12 +113,23 @@ public interface ServerEndpointConfig extends EndpointConfig {
this.path = path;
}
+ /**
+ * Builds and returns a {@link ServerEndpointConfig} with the configured settings.
+ *
+ * @return The configured server endpoint configuration
+ */
public ServerEndpointConfig build() {
return new DefaultServerEndpointConfig(endpointClass, path, subprotocols, extensions, encoders, decoders,
configurator);
}
+ /**
+ * Sets the list of encoder classes to use for the WebSocket connection.
+ *
+ * @param encoders The list of encoder classes
+ * @return This builder instance
+ */
public Builder encoders(List<Class<? extends Encoder>> encoders) {
if (encoders == null || encoders.isEmpty()) {
this.encoders = Collections.emptyList();
@@ -99,6 +140,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the list of decoder classes to use for the WebSocket connection.
+ *
+ * @param decoders The list of decoder classes
+ * @return This builder instance
+ */
public Builder decoders(List<Class<? extends Decoder>> decoders) {
if (decoders == null || decoders.isEmpty()) {
this.decoders = Collections.emptyList();
@@ -109,6 +156,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the list of sub-protocols supported by the endpoint.
+ *
+ * @param subprotocols The list of sub-protocols
+ * @return This builder instance
+ */
public Builder subprotocols(List<String> subprotocols) {
if (subprotocols == null || subprotocols.isEmpty()) {
this.subprotocols = Collections.emptyList();
@@ -119,6 +172,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the list of extensions supported by the endpoint.
+ *
+ * @param extensions The list of extensions
+ * @return This builder instance
+ */
public Builder extensions(List<Extension> extensions) {
if (extensions == null || extensions.isEmpty()) {
this.extensions = Collections.emptyList();
@@ -129,6 +188,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
}
+ /**
+ * Sets the configurator to use for the WebSocket handshake.
+ *
+ * @param serverEndpointConfigurator The configurator, or {@code null} to use the default
+ * @return This builder instance
+ */
public Builder configurator(Configurator serverEndpointConfigurator) {
if (serverEndpointConfigurator == null) {
this.configurator = Configurator.fetchContainerDefaultConfigurator();
@@ -140,8 +205,18 @@ public interface ServerEndpointConfig extends EndpointConfig {
}
+ /**
+ * Provides a mechanism to customize the WebSocket handshake for server endpoints.
+ * Applications may subclass this to inspect or modify the handshake.
+ */
class Configurator {
+ /**
+ * Creates a new instance of the Configurator.
+ */
+ public Configurator() {
+ }
+
private static volatile Configurator defaultImpl = null;
private static final Object defaultImplLock = new Object();
@@ -195,22 +270,61 @@ public interface ServerEndpointConfig extends EndpointConfig {
return fetchContainerDefaultConfigurator();
}
+ /**
+ * Determines the sub-protocol to use for the WebSocket connection by comparing the
+ * supported and requested sub-protocols.
+ *
+ * @param supported The list of sub-protocols supported by the endpoint
+ * @param requested The list of sub-protocols requested by the client
+ * @return The negotiated sub-protocol, or {@code null} if none matches
+ */
public String getNegotiatedSubprotocol(List<String> supported, List<String> requested) {
return fetchContainerDefaultConfigurator().getNegotiatedSubprotocol(supported, requested);
}
+ /**
+ * Determines the extensions to use for the WebSocket connection by comparing the
+ * installed and requested extensions.
+ *
+ * @param installed The list of extensions installed on the server
+ * @param requested The list of extensions requested by the client
+ * @return The list of negotiated extensions
+ */
public List<Extension> getNegotiatedExtensions(List<Extension> installed, List<Extension> requested) {
return fetchContainerDefaultConfigurator().getNegotiatedExtensions(installed, requested);
}
+ /**
+ * Checks whether the given Origin header value is acceptable. The default implementation
+ * always returns {@code true}.
+ *
+ * @param originHeaderValue The Origin header value to check
+ * @return {@code true} if the origin is acceptable
+ */
public boolean checkOrigin(String originHeaderValue) {
return fetchContainerDefaultConfigurator().checkOrigin(originHeaderValue);
}
+ /**
+ * Provides the opportunity to modify the handshake before it is completed. This method
+ * is called after the sub-protocol and extensions have been negotiated.
+ *
+ * @param sec The server endpoint configuration
+ * @param request The handshake request
+ * @param response The handshake response
+ */
public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) {
fetchContainerDefaultConfigurator().modifyHandshake(sec, request, response);
}
+ /**
+ * Creates a new instance of the endpoint class.
+ *
+ * @param <T> The type of the endpoint class
+ * @param clazz The endpoint class
+ * @return A new instance of the endpoint
+ * @throws InstantiationException If the endpoint cannot be instantiated
+ */
public <T extends Object> T getEndpointInstance(Class<T> clazz) throws InstantiationException {
return fetchContainerDefaultConfigurator().getEndpointInstance(clazz);
}
diff --git a/java/jakarta/xml/ws/WebServiceRef.java b/java/jakarta/xml/ws/WebServiceRef.java
index 3c7e7a4738..e90a6f9c3c 100644
--- a/java/jakarta/xml/ws/WebServiceRef.java
+++ b/java/jakarta/xml/ws/WebServiceRef.java
@@ -21,19 +21,48 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Declares a reference to a web service. The WebServiceRef annotation can be applied to a field or method to inject
+ * a reference to a web service, or to a class to declare web service dependencies.
+ */
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
-
public @interface WebServiceRef {
+
+ /**
+ * The name for the web service reference. The name is relative to the default initial context.
+ *
+ * @return the name of the web service reference
+ */
String name() default "";
+ /**
+ * The type of the injected object, typically the service endpoint interface.
+ *
+ * @return the type class
+ */
@SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
Class type() default Object.class;
+ /**
+ * The web service class, typically the service endpoint interface class.
+ *
+ * @return the web service class
+ */
@SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
Class value() default Object.class;
+ /**
+ * The location of the WSDL document for the web service.
+ *
+ * @return the WSDL location
+ */
String wsdlLocation() default "";
+ /**
+ * A provider-specific name that this reference should be mapped to.
+ *
+ * @return the provider-specific mapped name
+ */
String mappedName() default "";
}
diff --git a/java/jakarta/xml/ws/WebServiceRefs.java b/java/jakarta/xml/ws/WebServiceRefs.java
index 0b69d9e1f2..020d86a674 100644
--- a/java/jakarta/xml/ws/WebServiceRefs.java
+++ b/java/jakarta/xml/ws/WebServiceRefs.java
@@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Groups multiple {@link WebServiceRef} annotations on a single declaration. Use this annotation when a class has
+ * dependencies on more than one web service.
+ */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-
public @interface WebServiceRefs {
+
+ /**
+ * The array of WebServiceRef annotations.
+ *
+ * @return the WebServiceRef annotations
+ */
WebServiceRef[] value();
}
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: (tomcat) branch 11.0.x updated: Fix Jakarta EE APIs javadoc issues
Posted by Mark Thomas <ma...@apache.org>.
On 11/05/2026 10:17, Rémy Maucherat wrote:
> On Mon, May 11, 2026 at 11:16 AM <re...@apache.org> wrote:
>>
>> This is an automated email from the ASF dual-hosted git repository.
>>
>> rmaucher pushed a commit to branch 11.0.x
>> in repository https://gitbox.apache.org/repos/asf/tomcat.git
>>
>>
>> The following commit(s) were added to refs/heads/11.0.x by this push:
>> new 9d8b4c99e9 Fix Jakarta EE APIs javadoc issues
>> 9d8b4c99e9 is described below
>>
>> commit 9d8b4c99e9075901a651fbb3152981a547e96121
>> Author: remm <re...@apache.org>
>> AuthorDate: Sat May 9 09:04:07 2026 +0200
>>
>> Fix Jakarta EE APIs javadoc issues
>>
>> Includes TODO fixes and a few cut and paste issues.
>> Coauthored by OpenCode.
>> One question is if the explicit default constructor will mess up with
>> the signature validation from the TCK, in which case I will redo it
>> without that (so I will not backport for now).
>
> I have not noticed any TCK troubles caused by the change.
I haven't checked exhaustively but there first couple of classes I
checked, the signature file already included the default constructor so
an explicit declaration should be fine.
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: (tomcat) branch 11.0.x updated: Fix Jakarta EE APIs javadoc issues
Posted by Rémy Maucherat <re...@apache.org>.
On Mon, May 11, 2026 at 11:16 AM <re...@apache.org> wrote:
>
> This is an automated email from the ASF dual-hosted git repository.
>
> rmaucher pushed a commit to branch 11.0.x
> in repository https://gitbox.apache.org/repos/asf/tomcat.git
>
>
> The following commit(s) were added to refs/heads/11.0.x by this push:
> new 9d8b4c99e9 Fix Jakarta EE APIs javadoc issues
> 9d8b4c99e9 is described below
>
> commit 9d8b4c99e9075901a651fbb3152981a547e96121
> Author: remm <re...@apache.org>
> AuthorDate: Sat May 9 09:04:07 2026 +0200
>
> Fix Jakarta EE APIs javadoc issues
>
> Includes TODO fixes and a few cut and paste issues.
> Coauthored by OpenCode.
> One question is if the explicit default constructor will mess up with
> the signature validation from the TCK, in which case I will redo it
> without that (so I will not backport for now).
I have not noticed any TCK troubles caused by the change.
Rémy
> ---
> java/jakarta/annotation/Generated.java | 16 ++-
> java/jakarta/annotation/Priority.java | 6 +-
> java/jakarta/annotation/Resource.java | 35 +++++--
> java/jakarta/annotation/Resources.java | 5 +-
> java/jakarta/annotation/security/DeclareRoles.java | 11 +-
> java/jakarta/annotation/security/DenyAll.java | 6 ++
> java/jakarta/annotation/security/PermitAll.java | 6 ++
> java/jakarta/annotation/security/RolesAllowed.java | 12 ++-
> java/jakarta/annotation/security/RunAs.java | 10 +-
> .../annotation/sql/DataSourceDefinition.java | 95 +++++++++++++----
> .../annotation/sql/DataSourceDefinitions.java | 8 +-
> java/jakarta/ejb/EJB.java | 38 ++++++-
> java/jakarta/ejb/EJBs.java | 11 +-
> java/jakarta/el/BeanNameELResolver.java | 8 ++
> java/jakarta/el/BeanNameResolver.java | 9 +-
> java/jakarta/el/CompositeELResolver.java | 15 +++
> java/jakarta/el/ELClass.java | 14 +++
> java/jakarta/el/ELContext.java | 50 +++++++++
> java/jakarta/el/ELContextEvent.java | 13 +++
> java/jakarta/el/ELContextListener.java | 13 +++
> java/jakarta/el/ELManager.java | 98 ++++++++++++++++++
> java/jakarta/el/ELProcessor.java | 86 +++++++++++++++-
> java/jakarta/el/ELResolver.java | 17 +++
> java/jakarta/el/EvaluationListener.java | 10 ++
> java/jakarta/el/Expression.java | 21 +++-
> java/jakarta/el/ExpressionFactory.java | 35 ++++++-
> java/jakarta/el/FunctionMapper.java | 24 +++++
> java/jakarta/el/ImportHandler.java | 57 ++++++++++-
> java/jakarta/el/LambdaExpression.java | 45 ++++++++
> java/jakarta/el/ListELResolver.java | 18 ++++
> java/jakarta/el/MapELResolver.java | 18 ++++
> java/jakarta/el/MethodExpression.java | 16 +++
> java/jakarta/el/MethodInfo.java | 29 ++++++
> java/jakarta/el/MethodNotFoundException.java | 22 ++++
> java/jakarta/el/MethodReference.java | 12 +++
> java/jakarta/el/OptionalELResolver.java | 6 ++
> java/jakarta/el/PropertyNotFoundException.java | 27 +++++
> java/jakarta/el/PropertyNotWritableException.java | 27 +++++
> java/jakarta/el/RecordELResolver.java | 7 ++
> java/jakarta/el/ResourceBundleELResolver.java | 18 ++++
> java/jakarta/el/StandardELContext.java | 29 ++++++
> java/jakarta/el/StaticFieldELResolver.java | 11 ++
> java/jakarta/el/TypeConverter.java | 11 ++
> java/jakarta/el/ValueExpression.java | 33 ++++++
> java/jakarta/el/ValueReference.java | 23 +++++
> java/jakarta/el/VariableMapper.java | 25 ++++-
> java/jakarta/mail/Authenticator.java | 18 ++++
> java/jakarta/mail/PasswordAuthentication.java | 12 +++
> java/jakarta/mail/Session.java | 22 ++++
> java/jakarta/mail/internet/InternetAddress.java | 11 ++
> java/jakarta/mail/internet/MimeMessage.java | 19 ++++
> java/jakarta/mail/internet/MimePart.java | 4 +
> java/jakarta/mail/internet/MimePartDataSource.java | 9 ++
> java/jakarta/persistence/PersistenceContext.java | 30 +++++-
> .../persistence/PersistenceContextType.java | 16 ++-
> java/jakarta/persistence/PersistenceContexts.java | 9 +-
> java/jakarta/persistence/PersistenceProperty.java | 15 ++-
> java/jakarta/persistence/PersistenceUnit.java | 16 ++-
> java/jakarta/persistence/PersistenceUnits.java | 9 +-
> java/jakarta/persistence/SynchronizationType.java | 9 ++
> .../security/auth/message/AuthException.java | 12 +++
> java/jakarta/security/auth/message/AuthStatus.java | 23 +++++
> java/jakarta/security/auth/message/ClientAuth.java | 4 +
> .../jakarta/security/auth/message/MessageInfo.java | 38 +++++++
> .../security/auth/message/MessagePolicy.java | 99 ++++++++++++++++++
> java/jakarta/security/auth/message/ServerAuth.java | 7 ++
> .../message/callback/CallerPrincipalCallback.java | 34 +++++-
> .../auth/message/callback/CertStoreCallback.java | 16 ++-
> .../message/callback/GroupPrincipalCallback.java | 19 ++++
> .../callback/PasswordValidationCallback.java | 49 ++++++++-
> .../auth/message/callback/PrivateKeyCallback.java | 113 +++++++++++++++++++-
> .../auth/message/callback/SecretKeyCallback.java | 37 +++++++
> .../auth/message/callback/TrustStoreCallback.java | 16 +++
> .../security/auth/message/config/AuthConfig.java | 31 ++++++
> .../auth/message/config/AuthConfigFactory.java | 112 ++++++++++++++++++++
> .../auth/message/config/AuthConfigProvider.java | 30 ++++++
> .../auth/message/config/ClientAuthConfig.java | 15 +++
> .../auth/message/config/ClientAuthContext.java | 5 +
> .../auth/message/config/RegistrationListener.java | 9 ++
> .../auth/message/config/ServerAuthConfig.java | 12 +++
> .../auth/message/config/ServerAuthContext.java | 7 ++
> .../auth/message/module/ClientAuthModule.java | 21 ++++
> .../auth/message/module/ServerAuthModule.java | 25 +++++
> java/jakarta/servlet/AsyncContext.java | 34 ++++--
> java/jakarta/servlet/GenericFilter.java | 13 ++-
> java/jakarta/servlet/HttpConstraintElement.java | 12 +--
> java/jakarta/servlet/ServletContext.java | 84 ++++++++++-----
> java/jakarta/servlet/ServletRequest.java | 53 ++++++----
> java/jakarta/servlet/ServletRequestWrapper.java | 8 +-
> java/jakarta/servlet/ServletResponseWrapper.java | 6 +-
> java/jakarta/servlet/annotation/HandlesTypes.java | 8 +-
> .../servlet/annotation/MultipartConfig.java | 9 ++
> java/jakarta/servlet/annotation/WebFilter.java | 22 +++-
> java/jakarta/servlet/annotation/WebInitParam.java | 6 ++
> java/jakarta/servlet/annotation/WebListener.java | 2 +
> java/jakarta/servlet/annotation/WebServlet.java | 86 ++++++++++------
> java/jakarta/servlet/http/HttpFilter.java | 7 ++
> java/jakarta/servlet/http/HttpServletMapping.java | 36 ++++---
> java/jakarta/servlet/http/PushBuilder.java | 6 +-
> .../transaction/HeuristicCommitException.java | 14 +++
> .../transaction/HeuristicMixedException.java | 14 +++
> .../transaction/HeuristicRollbackException.java | 14 +++
> .../transaction/InvalidTransactionException.java | 13 +++
> .../jakarta/transaction/NotSupportedException.java | 11 ++
> java/jakarta/transaction/RollbackException.java | 11 ++
> java/jakarta/transaction/Status.java | 33 ++++++
> java/jakarta/transaction/Synchronization.java | 17 +++
> java/jakarta/transaction/SystemException.java | 21 ++++
> java/jakarta/transaction/Transaction.java | 63 ++++++++++++
> java/jakarta/transaction/TransactionManager.java | 68 ++++++++++++
> .../transaction/TransactionRequiredException.java | 11 ++
> .../TransactionRolledbackException.java | 11 ++
> .../TransactionSynchronizationRegistry.java | 40 ++++++++
> java/jakarta/transaction/UserTransaction.java | 47 +++++++++
> java/jakarta/websocket/ClientEndpoint.java | 25 +++++
> java/jakarta/websocket/ClientEndpointConfig.java | 82 +++++++++++++++
> java/jakarta/websocket/CloseReason.java | 106 +++++++++++++++++++
> java/jakarta/websocket/ContainerProvider.java | 11 ++
> java/jakarta/websocket/DecodeException.java | 45 ++++++++
> java/jakarta/websocket/Decoder.java | 68 ++++++++++++
> java/jakarta/websocket/DeploymentException.java | 14 +++
> java/jakarta/websocket/EncodeException.java | 24 +++++
> java/jakarta/websocket/Encoder.java | 58 ++++++++++-
> java/jakarta/websocket/Endpoint.java | 10 ++
> java/jakarta/websocket/EndpointConfig.java | 19 ++++
> java/jakarta/websocket/Extension.java | 28 +++++
> java/jakarta/websocket/HandshakeResponse.java | 8 ++
> java/jakarta/websocket/MessageHandler.java | 16 +++
> java/jakarta/websocket/OnClose.java | 4 +
> java/jakarta/websocket/OnError.java | 4 +
> java/jakarta/websocket/OnMessage.java | 11 ++
> java/jakarta/websocket/OnOpen.java | 4 +
> java/jakarta/websocket/RemoteEndpoint.java | 22 ++++
> java/jakarta/websocket/SendHandler.java | 8 ++
> java/jakarta/websocket/SendResult.java | 14 +++
> java/jakarta/websocket/Session.java | 83 +++++++++++++++
> java/jakarta/websocket/SessionException.java | 18 ++++
> java/jakarta/websocket/WebSocketContainer.java | 22 ++++
> .../jakarta/websocket/server/HandshakeRequest.java | 44 ++++++++
> java/jakarta/websocket/server/PathParam.java | 6 ++
> java/jakarta/websocket/server/ServerContainer.java | 13 +++
> java/jakarta/websocket/server/ServerEndpoint.java | 25 +++++
> .../websocket/server/ServerEndpointConfig.java | 114 +++++++++++++++++++++
> java/jakarta/xml/ws/WebServiceRef.java | 31 +++++-
> java/jakarta/xml/ws/WebServiceRefs.java | 11 +-
> 145 files changed, 3585 insertions(+), 182 deletions(-)
>
> diff --git a/java/jakarta/annotation/Generated.java b/java/jakarta/annotation/Generated.java
> index 19cbed8bc6..8251be3970 100644
> --- a/java/jakarta/annotation/Generated.java
> +++ b/java/jakarta/annotation/Generated.java
> @@ -33,18 +33,26 @@ import java.lang.annotation.Target;
> @Retention(RetentionPolicy.SOURCE)
> public @interface Generated {
> /**
> - * @return The name of the code generator. It is recommended that the fully qualified name of the code generator is
> - * used.
> + * Specifies the name(s) of the tool(s) that generated the annotated element.
> + * It is recommended that the fully qualified name of the code generator is used.
> + *
> + * @return the array of code generator names
> */
> String[] value();
>
> /**
> - * @return The date the code was generated
> + * Specifies the date and time when the code was generated, typically in
> + * ISO 8601 format. An empty string indicates the date is not specified.
> + *
> + * @return the code generation date, or an empty string if not specified
> */
> String date() default "";
>
> /**
> - * @return Additional comments (if any) related to the code generation
> + * Provides additional comments or metadata related to the code generation
> + * process, such as version information or configuration details.
> + *
> + * @return additional comments about the code generation, or an empty string if none
> */
> String comments() default "";
> }
> diff --git a/java/jakarta/annotation/Priority.java b/java/jakarta/annotation/Priority.java
> index c44be40d7f..4809275165 100644
> --- a/java/jakarta/annotation/Priority.java
> +++ b/java/jakarta/annotation/Priority.java
> @@ -31,7 +31,11 @@ import java.lang.annotation.RetentionPolicy;
> public @interface Priority {
>
> /**
> - * @return the int value
> + * Specifies the priority value used to determine the ordering of the annotated
> + * element. Lower values indicate higher priority. The annotated class or
> + * parameter defines how the priority value is interpreted and applied.
> + *
> + * @return the priority ordering value
> */
> int value();
> }
> diff --git a/java/jakarta/annotation/Resource.java b/java/jakarta/annotation/Resource.java
> index 692d13418e..a66f5fc621 100644
> --- a/java/jakarta/annotation/Resource.java
> +++ b/java/jakarta/annotation/Resource.java
> @@ -48,7 +48,10 @@ public @interface Resource {
> }
>
> /**
> - * @return a String with the name of the resource
> + * Specifies the logical name of the resource. If not specified, the container
> + * derives the name from the field or method to which the annotation is applied.
> + *
> + * @return the logical name of the resource
> */
> String name() default "";
>
> @@ -60,29 +63,49 @@ public @interface Resource {
> Class<?> type() default Object.class;
>
> /**
> - * @return the AuthenticationType of the resource default CONTAINER
> + * Specifies the authentication type for the resource. Container authentication
> + * means the container handles authentication, while application authentication
> + * means the application code is responsible for authentication.
> + *
> + * @return the authentication type, defaulting to {@link AuthenticationType#CONTAINER}
> */
> AuthenticationType authenticationType() default AuthenticationType.CONTAINER;
>
> /**
> - * @return true (default) if the resource is shareable, or false if not
> + * Indicates whether the resource can be shared among multiple injection points.
> + * When true, the same resource instance may be injected into multiple components.
> + * When false, each injection point receives a distinct resource instance.
> + *
> + * @return true if the resource is shareable across injection points, false otherwise
> */
> boolean shareable() default true;
>
> /**
> - * @return a string with the description for the resource
> + * Provides a human-readable description of the resource for documentation
> + * and administrative purposes.
> + *
> + * @return the resource description
> */
> String description() default "";
>
> /**
> - * @return a string with the mappedName of the resource
> + * Specifies a product-dependent name for the resource, allowing the container
> + * to map the logical resource name to a physical resource in a vendor-specific
> + * manner. This is typically used for environment-specific configuration.
> + *
> + * @return the product-specific mapped name for the resource
> */
> String mappedName() default "";
>
> /**
> + * Specifies the JNDI lookup name for the resource. This attribute allows
> + * explicit control over the JNDI name used to locate the resource, overriding
> + * the default name derivation. The lookup name is typically prefixed with
> + * "java:comp/env/" for component environment entries.
> + *
> * @since Common Annotations 1.1
> *
> - * @return The name of the entry, if any, to use for this resource
> + * @return the JNDI lookup name for the resource
> */
> String lookup() default "";
> }
> diff --git a/java/jakarta/annotation/Resources.java b/java/jakarta/annotation/Resources.java
> index 6ade76d6a6..bf668c6f1f 100644
> --- a/java/jakarta/annotation/Resources.java
> +++ b/java/jakarta/annotation/Resources.java
> @@ -33,7 +33,10 @@ import java.lang.annotation.Target;
> public @interface Resources {
>
> /**
> - * @return a Resource[] with the value of this Resources
> + * Specifies the array of {@link Resource} annotations that define the resources
> + * required by the annotated component.
> + *
> + * @return the array of resource definitions
> */
> Resource[] value();
> }
> diff --git a/java/jakarta/annotation/security/DeclareRoles.java b/java/jakarta/annotation/security/DeclareRoles.java
> index 3762af6a94..434aea50fd 100644
> --- a/java/jakarta/annotation/security/DeclareRoles.java
> +++ b/java/jakarta/annotation/security/DeclareRoles.java
> @@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> /**
> + * Declares that role names used in security constraints for the annotated
> + * enterprise bean should be treated as declared roles. When this annotation
> + * is present, the container must create any roles referenced in security
> + * constraints that are not explicitly defined in the deployment descriptor.
> + *
> * @since Common Annotations 1.0
> */
> @Documented
> @@ -31,7 +36,11 @@ import java.lang.annotation.Target;
> public @interface DeclareRoles {
>
> /**
> - * @return a String[] with the roles
> + * Specifies the declared role names that should be recognized by the container.
> + * These roles may be referenced in security constraints without being explicitly
> + * defined in the deployment descriptor.
> + *
> + * @return the array of declared role names
> */
> String[] value();
> }
> diff --git a/java/jakarta/annotation/security/DenyAll.java b/java/jakarta/annotation/security/DenyAll.java
> index 9944210ce7..10db8d2a76 100644
> --- a/java/jakarta/annotation/security/DenyAll.java
> +++ b/java/jakarta/annotation/security/DenyAll.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> /**
> + * Indicates that all access to the annotated enterprise bean or business method
> + * is denied. When applied at the class level, all security roles are prohibited
> + * from invoking any business method of the bean. When applied at the method level,
> + * the specified method is inaccessible to all roles. This annotation takes
> + * precedence over {@link PermitAll} and {@link RolesAllowed}.
> + *
> * @since Common Annotations 1.0
> */
> @Documented
> diff --git a/java/jakarta/annotation/security/PermitAll.java b/java/jakarta/annotation/security/PermitAll.java
> index 0e0c784c65..d129f8f2bc 100644
> --- a/java/jakarta/annotation/security/PermitAll.java
> +++ b/java/jakarta/annotation/security/PermitAll.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> /**
> + * Indicates that all authenticated users are permitted to access the annotated
> + * enterprise bean or business method. When applied at the class level, any
> + * authenticated user may invoke any business method of the bean. When applied
> + * at the method level, the specified method is accessible to all authenticated
> + * users. This annotation takes precedence over {@link RolesAllowed}.
> + *
> * @since Common Annotations 1.0
> */
> @Documented
> diff --git a/java/jakarta/annotation/security/RolesAllowed.java b/java/jakarta/annotation/security/RolesAllowed.java
> index 7092d01ab3..48b003de31 100644
> --- a/java/jakarta/annotation/security/RolesAllowed.java
> +++ b/java/jakarta/annotation/security/RolesAllowed.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> /**
> + * Specifies the security roles that are allowed to access the annotated enterprise
> + * bean or business method. When applied at the class level, only the listed roles
> + * may invoke any business method of the bean. When applied at the method level,
> + * only the listed roles may invoke the specified method. This annotation is
> + * mutually exclusive with {@link PermitAll} and {@link DenyAll}.
> + *
> * @since Common Annotations 1.0
> */
> @Documented
> @@ -31,7 +37,11 @@ import java.lang.annotation.Target;
> public @interface RolesAllowed {
>
> /**
> - * @return a String[] of the allowed roles
> + * Specifies the security role names that are authorized to access the
> + * annotated component or method. Only callers assigned one of these roles
> + * will be permitted access.
> + *
> + * @return the array of authorized role names
> */
> String[] value();
> }
> diff --git a/java/jakarta/annotation/security/RunAs.java b/java/jakarta/annotation/security/RunAs.java
> index d5029b7ecc..8d935eb51c 100644
> --- a/java/jakarta/annotation/security/RunAs.java
> +++ b/java/jakarta/annotation/security/RunAs.java
> @@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> /**
> + * Defines the run-as security role for an enterprise bean. The container assumes
> + * the specified role as the caller identity for all business method invocations
> + * made by the bean, regardless of the actual caller's identity. This allows the
> + * bean to access resources with a consistent security context.
> + *
> * @since Common Annotations 1.0
> */
> @Documented
> @@ -31,7 +36,10 @@ import java.lang.annotation.Target;
> public @interface RunAs {
>
> /**
> - * @return a String with the value for RunAs
> + * Specifies the security role name that the container should assume as the
> + * caller identity when executing business methods on behalf of this component.
> + *
> + * @return the run-as role name
> */
> String value();
> }
> diff --git a/java/jakarta/annotation/sql/DataSourceDefinition.java b/java/jakarta/annotation/sql/DataSourceDefinition.java
> index 9e5c46d0f3..0bea20aa2b 100644
> --- a/java/jakarta/annotation/sql/DataSourceDefinition.java
> +++ b/java/jakarta/annotation/sql/DataSourceDefinition.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> /**
> + * Defines a data source for dependency injection via the {@link jakarta.annotation.Resource}
> + * annotation. This annotation allows developers to declaratively specify the properties
> + * of a JDBC data source, including connection details, pool sizing, and transactional
> + * behavior. The container creates and manages the data source based on the specified
> + * configuration, making it available for injection into application components.
> + *
> * @since Common Annotations 1.1
> */
> @Target(ElementType.TYPE)
> @@ -31,92 +37,145 @@ import java.lang.annotation.Target;
> public @interface DataSourceDefinition {
>
> /**
> - * @return the className
> + * Specifies the fully qualified class name of the JDBC driver or the Jakarta
> + * Connector connection factory class that implements this data source.
> + *
> + * @return the fully qualified class name of the data source implementation
> */
> String className();
>
> /**
> - * @return the name
> + * Specifies the JNDI name under which the data source will be registered.
> + * This is the lookup name used for dependency injection or explicit JNDI
> + * lookup of the data source.
> + *
> + * @return the JNDI name for the data source
> */
> String name();
>
> /**
> - * @return the description
> + * Provides a human-readable description of the data source for documentation
> + * and administrative purposes.
> + *
> + * @return the description of the data source
> */
> String description() default "";
>
> /**
> - * @return the url
> + * Specifies the JDBC connection URL for the database. This URL is used by
> + * the driver to establish connections to the database server.
> + *
> + * @return the JDBC connection URL
> */
> String url() default "";
>
> /**
> - * @return the user
> + * Specifies the database user name used to establish connections.
> + *
> + * @return the database user name
> */
> String user() default "";
>
> /**
> - * @return the password
> + * Specifies the password for the database user account used to establish connections.
> + *
> + * @return the database password
> */
> String password() default "";
>
> /**
> - * @return database name
> + * Specifies the name of the database to connect to. This is used in conjunction
> + * with the server name and port number to locate the target database.
> + *
> + * @return the database name
> */
> String databaseName() default "";
>
> /**
> - * @return the port number
> + * Specifies the network port number on which the database server is listening.
> + * A value of -1 indicates the default port for the database type.
> + *
> + * @return the database server port number, or -1 for the default
> */
> int portNumber() default -1;
>
> /**
> - * @return the server name
> + * Specifies the host name or IP address of the database server.
> + *
> + * @return the database server host name, defaulting to "localhost"
> */
> String serverName() default "localhost";
>
> /**
> - * @return the isolation level
> + * Specifies the transaction isolation level for connections from this data source,
> + * using the constants defined in {@link java.sql.Connection}. A value of -1
> + * indicates the database default isolation level should be used.
> + *
> + * @return the transaction isolation level, or -1 for the database default
> */
> int isolationLevel() default -1;
>
> /**
> - * @return true if the data source is transactional
> + * Indicates whether connections from this data source support container-managed
> + * transactions. When true, the data source participates in Jakarta Transactions.
> + *
> + * @return true if the data source participates in container-managed transactions
> */
> boolean transactional() default true;
>
> /**
> - * @return the initial pool size
> + * Specifies the number of connections to create when the connection pool is
> + * initialized. A value of -1 indicates the container default should be used.
> + *
> + * @return the initial number of connections in the pool, or -1 for default
> */
> int initialPoolSize() default -1;
>
> /**
> - * @return the max pool size
> + * Specifies the maximum number of connections that the pool may create.
> + * A value of -1 indicates the container default should be used.
> + *
> + * @return the maximum pool size, or -1 for the container default
> */
> int maxPoolSize() default -1;
>
> /**
> - * @return the min pool size
> + * Specifies the minimum number of connections that the pool must maintain.
> + * A value of -1 indicates the container default should be used.
> + *
> + * @return the minimum pool size, or -1 for the container default
> */
> int minPoolSize() default -1;
>
> /**
> - * @return the max idle time
> + * Specifies the maximum idle time in seconds before a connection is closed
> + * and removed from the pool. A value of -1 indicates no idle timeout.
> + *
> + * @return the maximum idle time in seconds, or -1 for no timeout
> */
> int maxIdleTime() default -1;
>
> /**
> - * @return the max statements
> + * Specifies the maximum number of prepared statements that may be cached
> + * per connection in the pool. A value of -1 indicates the container default.
> + *
> + * @return the maximum cached prepared statements per connection, or -1 for default
> */
> int maxStatements() default -1;
>
> /**
> - * @return a String[] with the properties
> + * Specifies additional connection properties in the form "name=value" strings.
> + * These properties are passed to the JDBC driver during connection establishment.
> + *
> + * @return the array of additional connection properties
> */
> String[] properties() default {};
>
> /**
> - * @return the login timeout
> + * Specifies the maximum time in seconds that the driver will wait when
> + * attempting to connect to the database. A value of 0 means no timeout.
> + *
> + * @return the login timeout in seconds, or 0 for no timeout
> */
> int loginTimeout() default 0;
> }
> diff --git a/java/jakarta/annotation/sql/DataSourceDefinitions.java b/java/jakarta/annotation/sql/DataSourceDefinitions.java
> index d40e357af5..ace5402e7a 100644
> --- a/java/jakarta/annotation/sql/DataSourceDefinitions.java
> +++ b/java/jakarta/annotation/sql/DataSourceDefinitions.java
> @@ -22,6 +22,10 @@ import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> /**
> + * Container annotation that holds multiple {@link DataSourceDefinition} annotations.
> + * This annotation is used to group several data source definitions when applied to
> + * the same type, following the standard Java annotation repetition pattern.
> + *
> * @since Common Annotations 1.1
> */
> @Target(ElementType.TYPE)
> @@ -29,7 +33,9 @@ import java.lang.annotation.Target;
> public @interface DataSourceDefinitions {
>
> /**
> - * @return a DataSourceDefinition[]
> + * Specifies the array of data source definitions contained within this container annotation.
> + *
> + * @return the array of {@link DataSourceDefinition} annotations
> */
> DataSourceDefinition[] value();
> }
> diff --git a/java/jakarta/ejb/EJB.java b/java/jakarta/ejb/EJB.java
> index cd5b24720c..94fab54075 100644
> --- a/java/jakarta/ejb/EJB.java
> +++ b/java/jakarta/ejb/EJB.java
> @@ -21,20 +21,56 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Declares a dependency on an enterprise bean. The EJB annotation can be applied to a field or method to inject
> + * a reference to an enterprise bean, or to a class to declare bean dependencies for the entire bean.
> + */
> @Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface EJB {
> +
> + /**
> + * The name element for the annotation. The name of an enterprise bean is relative to the javax.np.Context of
> + * the bean. The name must be unique within the bean.
> + *
> + * @return the name of the enterprise bean
> + */
> String name() default "";
>
> + /**
> + * A description of the enterprise bean reference.
> + *
> + * @return the description
> + */
> String description() default "";
>
> + /**
> + * The interface of the enterprise bean.
> + *
> + * @return the bean interface class
> + */
> @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
> Class beanInterface() default Object.class;
>
> + /**
> + * The name of the enterprise bean. The beanName is relative to the javax.naming.Context of the bean that
> + * owns this reference.
> + *
> + * @return the name of the enterprise bean
> + */
> String beanName() default "";
>
> + /**
> + * A provider-specific name that this reference should be mapped to. The entire name is provider-specific.
> + *
> + * @return the provider-specific mapped name
> + */
> String mappedName() default "";
>
> + /**
> + * A JNDI name used to locate the enterprise bean. The lookup element overrides the default JNDI lookup name.
> + *
> + * @return the JNDI lookup string
> + */
> String lookup() default "";
> }
> diff --git a/java/jakarta/ejb/EJBs.java b/java/jakarta/ejb/EJBs.java
> index 5f2647cb17..2457371609 100644
> --- a/java/jakarta/ejb/EJBs.java
> +++ b/java/jakarta/ejb/EJBs.java
> @@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple {@link EJB} annotations on a single declaration. Use this annotation when a class has dependencies
> + * on more than one enterprise bean.
> + */
> @Target(ElementType.TYPE)
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface EJBs {
> +
> + /**
> + * The array of EJB annotations.
> + *
> + * @return the EJB annotations
> + */
> EJB[] value();
> }
> diff --git a/java/jakarta/el/BeanNameELResolver.java b/java/jakarta/el/BeanNameELResolver.java
> index 8331e310f4..248b08fe4f 100644
> --- a/java/jakarta/el/BeanNameELResolver.java
> +++ b/java/jakarta/el/BeanNameELResolver.java
> @@ -19,12 +19,20 @@ package jakarta.el;
> import java.util.Objects;
>
> /**
> + * ELResolver that resolves bean names to bean instances using a {@link BeanNameResolver}. This resolver handles
> + * expressions where the base is {@code null} and the property is a {@link String} representing a bean name.
> + *
> * @since EL 3.0
> */
> public class BeanNameELResolver extends ELResolver {
>
> private final BeanNameResolver beanNameResolver;
>
> + /**
> + * Constructs a BeanNameELResolver with the specified BeanNameResolver.
> + *
> + * @param beanNameResolver the resolver used to look up beans by name
> + */
> public BeanNameELResolver(BeanNameResolver beanNameResolver) {
> this.beanNameResolver = beanNameResolver;
> }
> diff --git a/java/jakarta/el/BeanNameResolver.java b/java/jakarta/el/BeanNameResolver.java
> index 17754a1553..c8ab3a8661 100644
> --- a/java/jakarta/el/BeanNameResolver.java
> +++ b/java/jakarta/el/BeanNameResolver.java
> @@ -18,12 +18,19 @@ package jakarta.el;
>
> /**
> * Base implementation that provides a minimal default implementation that is intended to be extended by application
> - * developers.
> + * developers. Subclasses define the logic for resolving bean names to bean instances, checking read-only status,
> + * and determining whether new beans can be created.
> *
> * @since EL 3.0
> */
> public abstract class BeanNameResolver {
>
> + /**
> + * Default constructor for subclasses.
> + */
> + public BeanNameResolver() {
> + }
> +
> /**
> * Can this resolver resolve the given bean name?
> *
> diff --git a/java/jakarta/el/CompositeELResolver.java b/java/jakarta/el/CompositeELResolver.java
> index 8c9c1fc335..4a73d13d72 100644
> --- a/java/jakarta/el/CompositeELResolver.java
> +++ b/java/jakarta/el/CompositeELResolver.java
> @@ -20,6 +20,11 @@ import java.util.HashSet;
> import java.util.Objects;
> import java.util.Set;
>
> +/**
> + * ELResolver that delegates to an ordered list of other ELResolvers. When a property operation is performed, each
> + * contained resolver is invoked in order until one resolves the property. This is the standard mechanism for
> + * building a resolver chain in an EL context.
> + */
> public class CompositeELResolver extends ELResolver {
>
> private static final Class<?> SCOPED_ATTRIBUTE_EL_RESOLVER;
> @@ -62,6 +67,9 @@ public class CompositeELResolver extends ELResolver {
> private int typeConvertersSize;
> private ELResolver[] typeConverters;
>
> + /**
> + * Constructs an empty CompositeELResolver. Use {@link #add(ELResolver)} to add resolvers to the chain.
> + */
> public CompositeELResolver() {
> resolversSize = 0;
> resolvers = new ELResolver[8];
> @@ -70,6 +78,13 @@ public class CompositeELResolver extends ELResolver {
> typeConverters = new ELResolver[0];
> }
>
> + /**
> + * Adds an ELResolver to the end of the resolver chain.
> + *
> + * @param elResolver the resolver to add
> + *
> + * @throws NullPointerException if elResolver is {@code null}
> + */
> public void add(ELResolver elResolver) {
> Objects.requireNonNull(elResolver);
>
> diff --git a/java/jakarta/el/ELClass.java b/java/jakarta/el/ELClass.java
> index 0d003029ec..d72fd9bf0e 100644
> --- a/java/jakarta/el/ELClass.java
> +++ b/java/jakarta/el/ELClass.java
> @@ -17,16 +17,30 @@
> package jakarta.el;
>
> /**
> + * Wrapper for a {@link Class} object that enables access to static fields and methods from EL expressions. An
> + * ELClass instance is used as the base object when resolving static members, typically in conjunction with the
> + * {@link StaticFieldELResolver}.
> + *
> * @since EL 3.0
> */
> public class ELClass {
>
> private final Class<?> clazz;
>
> + /**
> + * Constructs an ELClass wrapping the specified Class.
> + *
> + * @param clazz the class to wrap
> + */
> public ELClass(Class<?> clazz) {
> this.clazz = clazz;
> }
>
> + /**
> + * Returns the wrapped Class.
> + *
> + * @return the wrapped Class
> + */
> public Class<?> getKlass() {
> return clazz;
> }
> diff --git a/java/jakarta/el/ELContext.java b/java/jakarta/el/ELContext.java
> index f99f82c0f7..d0f7e4adbe 100644
> --- a/java/jakarta/el/ELContext.java
> +++ b/java/jakarta/el/ELContext.java
> @@ -28,6 +28,11 @@ import java.util.Locale;
> import java.util.Map;
> import java.util.Objects;
>
> +/**
> + * Provides the context in which an EL expression is evaluated. An ELContext holds references to the
> + * {@link ELResolver}, {@link FunctionMapper}, {@link VariableMapper}, {@link ImportHandler}, locale, and other
> + * objects required for expression evaluation. Implementations include {@link StandardELContext}.
> + */
> public abstract class ELContext {
>
> private Locale locale;
> @@ -42,6 +47,9 @@ public abstract class ELContext {
>
> private Deque<Map<String,Object>> lambdaArguments = null;
>
> + /**
> + * Constructs an ELContext with the resolved flag set to {@code false}.
> + */
> public ELContext() {
> this.resolved = false;
> }
> @@ -53,6 +61,13 @@ public abstract class ELContext {
> return lambdaArguments;
> }
>
> + /**
> + * Sets the internal flag indicating whether a property has been resolved during the current
> + * evaluation step. This method is used by {@link ELResolver} implementations to signal that
> + * they have handled the current base/property combination.
> + *
> + * @param resolved {@code true} if a property has been resolved, {@code false} otherwise
> + */
> public void setPropertyResolved(boolean resolved) {
> this.resolved = resolved;
> }
> @@ -70,6 +85,13 @@ public abstract class ELContext {
> notifyPropertyResolved(base, property);
> }
>
> + /**
> + * Returns whether a property has been resolved during the current evaluation step.
> + * ELResolver implementations call {@link #setPropertyResolved(boolean)} to indicate resolution,
> + * and the expression evaluator checks this flag to determine if resolution was successful.
> + *
> + * @return {@code true} if a property has been resolved, {@code false} otherwise
> + */
> public boolean isPropertyResolved() {
> return this.resolved;
> }
> @@ -110,6 +132,11 @@ public abstract class ELContext {
> return this.map.get(key);
> }
>
> + /**
> + * Returns the ELResolver used to resolve properties and method invocations during expression evaluation.
> + *
> + * @return the ELResolver for this context
> + */
> public abstract ELResolver getELResolver();
>
> /**
> @@ -126,16 +153,39 @@ public abstract class ELContext {
> return importHandler;
> }
>
> + /**
> + * Returns the FunctionMapper used to resolve EL function names to Java methods during expression evaluation.
> + *
> + * @return the FunctionMapper for this context
> + */
> public abstract FunctionMapper getFunctionMapper();
>
> + /**
> + * Returns the locale associated with this EL context. The locale is used for type conversion
> + * operations such as parsing numbers and dates during expression evaluation.
> + *
> + * @return the locale for this context, or {@code null} if not set
> + */
> public Locale getLocale() {
> return this.locale;
> }
>
> + /**
> + * Sets the locale for this EL context. The locale is used for type conversion operations
> + * such as parsing numbers and dates during expression evaluation.
> + *
> + * @param locale the locale to use for this context
> + */
> public void setLocale(Locale locale) {
> this.locale = locale;
> }
>
> + /**
> + * Returns the VariableMapper used to resolve EL variable names to {@link ValueExpression}
> + * instances during expression evaluation.
> + *
> + * @return the VariableMapper for this context
> + */
> public abstract VariableMapper getVariableMapper();
>
> /**
> diff --git a/java/jakarta/el/ELContextEvent.java b/java/jakarta/el/ELContextEvent.java
> index b5bfda0e68..713e668b5e 100644
> --- a/java/jakarta/el/ELContextEvent.java
> +++ b/java/jakarta/el/ELContextEvent.java
> @@ -19,18 +19,31 @@ package jakarta.el;
> import java.io.Serial;
> import java.util.EventObject;
>
> +/**
> + * Event object passed to {@link ELContextListener} instances when an EL context is created or
> + * released. The source of this event is the {@link ELContext} that was created or released.
> + *
> + * @since EL 2.1
> + */
> public class ELContextEvent extends EventObject {
>
> @Serial
> private static final long serialVersionUID = 1255131906285426769L;
>
> /**
> + * Constructs an ELContextEvent with the specified ELContext as its source.
> + *
> * @param source The EL context that was the source of this event
> */
> public ELContextEvent(ELContext source) {
> super(source);
> }
>
> + /**
> + * Returns the ELContext that is the source of this event.
> + *
> + * @return the ELContext associated with this event
> + */
> public ELContext getELContext() {
> return (ELContext) this.getSource();
> }
> diff --git a/java/jakarta/el/ELContextListener.java b/java/jakarta/el/ELContextListener.java
> index d161362da7..31fb003165 100644
> --- a/java/jakarta/el/ELContextListener.java
> +++ b/java/jakarta/el/ELContextListener.java
> @@ -16,8 +16,21 @@
> */
> package jakarta.el;
>
> +/**
> + * Listener interface for EL context lifecycle events. Implementations are notified when an
> + * {@link ELContext} is created or released, allowing them to perform initialization or
> + * cleanup operations on the context.
> + *
> + * @since EL 2.1
> + */
> public interface ELContextListener extends java.util.EventListener {
>
> + /**
> + * Notification that an EL context has been created. Implementations can use this callback
> + * to register resources, resolvers, or other objects with the newly created context.
> + *
> + * @param event the event containing the ELContext that was created
> + */
> void contextCreated(ELContextEvent event);
>
> }
> diff --git a/java/jakarta/el/ELManager.java b/java/jakarta/el/ELManager.java
> index 4f552942cf..ae16a33909 100644
> --- a/java/jakarta/el/ELManager.java
> +++ b/java/jakarta/el/ELManager.java
> @@ -20,16 +20,38 @@ import java.lang.reflect.Method;
> import java.util.Map;
>
> /**
> + * Provides a simplified API for managing EL context, resolvers, functions, and variables. This class maintains a
> + * {@link StandardELContext} and provides convenience methods for adding resolvers, mapping functions, setting
> + * variables, and managing imports. It is used internally by {@link ELProcessor}.
> + *
> * @since EL 3.0
> */
> public class ELManager {
>
> private StandardELContext context = null;
>
> + /**
> + * Constructs an ELManager with a lazily initialized {@link StandardELContext}.
> + */
> + public ELManager() {
> + }
> +
> + /**
> + * Returns the {@link ExpressionFactory} used to create and evaluate EL expressions.
> + * The factory is obtained through the standard service discovery mechanism.
> + *
> + * @return the ExpressionFactory instance
> + */
> public static ExpressionFactory getExpressionFactory() {
> return Util.getExpressionFactory();
> }
>
> + /**
> + * Returns the {@link StandardELContext} managed by this ELManager, creating it on first access
> + * if it does not already exist.
> + *
> + * @return the StandardELContext instance
> + */
> public StandardELContext getELContext() {
> if (context == null) {
> context = new StandardELContext(getExpressionFactory());
> @@ -38,40 +60,110 @@ public class ELManager {
> return context;
> }
>
> + /**
> + * Replaces the current EL context with a new {@link StandardELContext} initialized from the
> + * given context. The new context copies the ELResolver chain, FunctionMapper, VariableMapper,
> + * and other settings from the provided context.
> + *
> + * @param context the ELContext from which to initialize the new context
> + *
> + * @return the previous StandardELContext, or {@code null} if none existed
> + */
> public ELContext setELContext(ELContext context) {
> StandardELContext oldContext = this.context;
> this.context = new StandardELContext(context);
> return oldContext;
> }
>
> + /**
> + * Adds a {@link BeanNameELResolver} to the resolver chain that uses the given
> + * {@link BeanNameResolver} to resolve top-level identifiers to managed beans.
> + *
> + * @param beanNameResolver the resolver for bean names
> + */
> public void addBeanNameResolver(BeanNameResolver beanNameResolver) {
> getELContext().addELResolver(new BeanNameELResolver(beanNameResolver));
> }
>
> + /**
> + * Adds an {@link ELResolver} to the front of the resolver chain in the managed EL context.
> + * Resolvers added first have higher priority during property resolution.
> + *
> + * @param resolver the ELResolver to add
> + */
> public void addELResolver(ELResolver resolver) {
> getELContext().addELResolver(resolver);
> }
>
> + /**
> + * Maps a static method to an EL function name with the given prefix and local name.
> + * The function can then be invoked in EL expressions as {@code prefix:function(args)}.
> + *
> + * @param prefix the namespace prefix for the function
> + * @param function the local function name
> + * @param method the static {@link java.lang.reflect.Method} to map
> + */
> public void mapFunction(String prefix, String function, Method method) {
> getELContext().getFunctionMapper().mapFunction(prefix, function, method);
> }
>
> + /**
> + * Registers a variable in the EL context's variable mapper. The variable can then be
> + * referenced by name in EL expressions. Passing a {@code null} expression removes
> + * the variable.
> + *
> + * @param variable the variable name
> + * @param expression the ValueExpression associated with the variable, or {@code null} to remove
> + */
> public void setVariable(String variable, ValueExpression expression) {
> getELContext().getVariableMapper().setVariable(variable, expression);
> }
>
> + /**
> + * Imports a static field or method so it can be referenced by its simple name in EL
> + * expressions. The argument must be a fully qualified name in the form
> + * {@code className.staticMemberName}.
> + *
> + * @param staticMemberName the fully qualified name of the static member to import
> + *
> + * @throws ELException if the static member cannot be found or is ambiguous
> + */
> public void importStatic(String staticMemberName) throws ELException {
> getELContext().getImportHandler().importStatic(staticMemberName);
> }
>
> + /**
> + * Imports a class so it can be referenced by its simple name in EL expressions.
> + * The argument must be a fully qualified class name.
> + *
> + * @param className the fully qualified class name to import
> + *
> + * @throws ELException if the class name is invalid or conflicts with an existing import
> + */
> public void importClass(String className) throws ELException {
> getELContext().getImportHandler().importClass(className);
> }
>
> + /**
> + * Imports all classes from a package so they can be referenced by their simple names
> + * in EL expressions.
> + *
> + * @param packageName the package name to import
> + */
> public void importPackage(String packageName) {
> getELContext().getImportHandler().importPackage(packageName);
> }
>
> + /**
> + * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
> + * is provided, it is stored under the given name. When {@code null} is provided, the
> + * bean with the given name is removed.
> + *
> + * @param name the bean name
> + * @param bean the bean object to define, or {@code null} to remove the bean
> + *
> + * @return the previous bean associated with the name, or {@code null} if there was none
> + */
> public Object defineBean(String name, Object bean) {
> Map<String,Object> localBeans = getELContext().getLocalBeans();
>
> @@ -82,6 +174,12 @@ public class ELManager {
> }
> }
>
> + /**
> + * Registers an {@link EvaluationListener} with the managed EL context. The listener
> + * will be notified before and after expression evaluation, and when properties are resolved.
> + *
> + * @param listener the EvaluationListener to register
> + */
> public void addEvaluationListener(EvaluationListener listener) {
> getELContext().addEvaluationListener(listener);
> }
> diff --git a/java/jakarta/el/ELProcessor.java b/java/jakarta/el/ELProcessor.java
> index d3f10f17b9..0b3795116e 100644
> --- a/java/jakarta/el/ELProcessor.java
> +++ b/java/jakarta/el/ELProcessor.java
> @@ -22,6 +22,10 @@ import java.util.HashSet;
> import java.util.Set;
>
> /**
> + * Provides a simple API for evaluating EL expressions in a standalone environment. This class wraps an
> + * {@link ELManager} and provides methods for evaluating expressions, defining beans and functions, and managing
> + * variables. It is the primary entry point for applications that use the EL API outside of a Jakarta EE container.
> + *
> * @since EL 3.0
> */
> public class ELProcessor {
> @@ -44,31 +48,82 @@ public class ELProcessor {
> private final ELContext context = manager.getELContext();
> private final ExpressionFactory factory = ELManager.getExpressionFactory();
>
> + /**
> + * Constructs an ELProcessor with a default {@link ELManager} and {@link StandardELContext}.
> + * The processor is ready to evaluate expressions immediately after construction.
> + */
> + public ELProcessor() {
> + }
>
> + /**
> + * Returns the {@link ELManager} that manages the EL context, resolvers, functions, and
> + * variables for this processor.
> + *
> + * @return the ELManager instance
> + */
> public ELManager getELManager() {
> return manager;
> }
>
> -
> + /**
> + * Evaluates the given EL expression and returns the result as the requested type.
> + * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
> + *
> + * @param <T> the expected result type
> + * @param expression the EL expression to evaluate
> + *
> + * @return the result of evaluating the expression, coerced to the requested type
> + *
> + * @throws ELException if the expression cannot be evaluated
> + */
> public <T> T eval(String expression) {
> @SuppressWarnings("unchecked")
> T result = (T) getValue(expression, Object.class);
> return result;
> }
>
> -
> + /**
> + * Evaluates the given EL expression and returns the result coerced to the expected type.
> + * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
> + *
> + * @param <T> the expected result type
> + * @param expression the EL expression to evaluate
> + * @param expectedType the class of the expected result type
> + *
> + * @return the result of evaluating the expression, coerced to the expected type
> + *
> + * @throws ELException if the expression cannot be evaluated
> + */
> public <T> T getValue(String expression, Class<T> expectedType) {
> ValueExpression ve = factory.createValueExpression(context, bracket(expression), expectedType);
> return ve.getValue(context);
> }
>
> -
> + /**
> + * Evaluates the given EL expression and sets the result to the specified value.
> + * This is used for EL assignment expressions. The expression is automatically wrapped
> + * in {@literal ${}} delimiters before evaluation.
> + *
> + * @param expression the EL expression to evaluate
> + * @param value the value to assign
> + *
> + * @throws ELException if the expression cannot be evaluated or the target is not writable
> + */
> public void setValue(String expression, Object value) {
> ValueExpression ve = factory.createValueExpression(context, bracket(expression), Object.class);
> ve.setValue(context, value);
> }
>
> -
> + /**
> + * Registers a variable in the EL context. The variable is associated with the result
> + * of evaluating the given expression. Passing a {@code null} expression removes the
> + * variable from the context.
> + *
> + * @param variable the variable name
> + * @param expression the EL expression to associate with the variable, or {@code null} to remove
> + *
> + * @throws ELException if the expression cannot be evaluated
> + */
> public void setVariable(String variable, String expression) {
> if (expression == null) {
> manager.setVariable(variable, null);
> @@ -78,7 +133,20 @@ public class ELProcessor {
> }
> }
>
> -
> + /**
> + * Registers a function in the EL context by looking up the static method in the given class.
> + * The method name may include a return type and parameter signature in the format
> + * {@code returnType methodName(paramTypes)}. The function is then callable in EL expressions
> + * as {@code prefix:function(args)}.
> + *
> + * @param prefix the namespace prefix for the function
> + * @param function the local function name, or empty to use the method name
> + * @param className the fully qualified name of the class containing the static method
> + * @param methodName the method name, optionally with return type and parameter signature
> + *
> + * @throws ClassNotFoundException if the class cannot be found or is not public
> + * @throws NoSuchMethodException if the method cannot be found or is not a public static method
> + */
> public void defineFunction(String prefix, String function, String className, String methodName)
> throws ClassNotFoundException, NoSuchMethodException {
>
> @@ -188,6 +256,14 @@ public class ELProcessor {
> }
>
>
> + /**
> + * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
> + * is provided, it is stored under the given name. When {@code null} is provided, the
> + * bean with the given name is removed.
> + *
> + * @param name the bean name
> + * @param bean the bean object to define, or {@code null} to remove the bean
> + */
> public void defineBean(String name, Object bean) {
> manager.defineBean(name, bean);
> }
> diff --git a/java/jakarta/el/ELResolver.java b/java/jakarta/el/ELResolver.java
> index e7dad5afcd..deaef98f2a 100644
> --- a/java/jakarta/el/ELResolver.java
> +++ b/java/jakarta/el/ELResolver.java
> @@ -16,8 +16,25 @@
> */
> package jakarta.el;
>
> +/**
> + * Base class for resolvers that resolve property references during EL expression evaluation.
> + * An ELResolver is responsible for resolving a property on a base object, determining its type,
> + * setting its value, and reporting whether it is read-only. Resolvers are chained together in
> + * an {@link ELContext}, and each resolver in the chain attempts to resolve the property until
> + * one succeeds. Implementations include {@link ListELResolver}, {@link MapELResolver}, and
> + * custom resolvers for application-specific object models.
> + *
> + * @since EL 2.1
> + */
> public abstract class ELResolver {
>
> + /**
> + * Constructs an ELResolver. Subclasses should invoke this constructor to initialize
> + * the base resolver state.
> + */
> + public ELResolver() {
> + }
> +
> /**
> * Obtain the value of the given property on the given object using the given context.
> *
> diff --git a/java/jakarta/el/EvaluationListener.java b/java/jakarta/el/EvaluationListener.java
> index 68c30985e0..836fac9e75 100644
> --- a/java/jakarta/el/EvaluationListener.java
> +++ b/java/jakarta/el/EvaluationListener.java
> @@ -17,10 +17,20 @@
> package jakarta.el;
>
> /**
> + * Listener interface for monitoring EL expression evaluation events. Implementations can track when expressions are
> + * evaluated and when properties are resolved during evaluation. Register an instance with an {@link ELContext} using
> + * {@link ELContext#addEvaluationListener(EvaluationListener)}.
> + *
> * @since EL 3.0
> */
> public abstract class EvaluationListener {
>
> + /**
> + * Constructs an EvaluationListener.
> + */
> + public EvaluationListener() {
> + }
> +
> /**
> * Fired before the evaluation of the expression.
> *
> diff --git a/java/jakarta/el/Expression.java b/java/jakarta/el/Expression.java
> index 9c833768d4..b241e37415 100644
> --- a/java/jakarta/el/Expression.java
> +++ b/java/jakarta/el/Expression.java
> @@ -20,13 +20,26 @@ import java.io.Serial;
> import java.io.Serializable;
>
> /**
> - *
> + * Base class for EL expression objects. An Expression represents a compiled EL expression that can be evaluated.
> + * Subclasses include {@link ValueExpression} and {@link MethodExpression}.
> */
> public abstract class Expression implements Serializable {
>
> @Serial
> private static final long serialVersionUID = -6663767980471823812L;
>
> + /**
> + * Constructs an Expression. Subclasses should invoke this constructor to initialize
> + * the base expression state.
> + */
> + public Expression() {
> + }
> +
> + /**
> + * Returns the original string representation of this EL expression as it was parsed.
> + *
> + * @return the string representation of this expression
> + */
> public abstract String getExpressionString();
>
> @Override
> @@ -35,6 +48,12 @@ public abstract class Expression implements Serializable {
> @Override
> public abstract int hashCode();
>
> + /**
> + * Returns whether this expression is a literal text expression, meaning it does not
> + * contain any variables, functions, or operators and evaluates to a constant value.
> + *
> + * @return {@code true} if this expression is a literal text, {@code false} otherwise
> + */
> public abstract boolean isLiteralText();
>
> }
> diff --git a/java/jakarta/el/ExpressionFactory.java b/java/jakarta/el/ExpressionFactory.java
> index bda510cea1..e327f7338b 100644
> --- a/java/jakarta/el/ExpressionFactory.java
> +++ b/java/jakarta/el/ExpressionFactory.java
> @@ -35,10 +35,21 @@ import java.util.concurrent.locks.ReadWriteLock;
> import java.util.concurrent.locks.ReentrantReadWriteLock;
>
> /**
> - * @since 2.1
> + * Factory for creating {@link ValueExpression} and {@link MethodExpression} instances, and for coercing objects to
> + * specific types. Implementations parse and compile EL expressions. Use {@link #newInstance()} to obtain an instance
> + * using the standard discovery mechanism.
> + *
> + * @since EL 2.1
> */
> public abstract class ExpressionFactory {
>
> + /**
> + * Constructs an ExpressionFactory. Subclasses should invoke this constructor to initialize
> + * the base factory state.
> + */
> + public ExpressionFactory() {
> + }
> +
> private static final String PROPERTY_NAME = "jakarta.el.ExpressionFactory";
>
> private static final String PROPERTY_FILE =
> @@ -170,6 +181,16 @@ public abstract class ExpressionFactory {
> */
> public abstract ValueExpression createValueExpression(ELContext context, String expression, Class<?> expectedType);
>
> + /**
> + * Creates a {@link ValueExpression} that, when evaluated, returns the given instance
> + * of the specified type. This is a convenience method for creating a constant value
> + * expression without requiring an {@link ELContext}.
> + *
> + * @param instance the constant value to wrap
> + * @param expectedType the expected type of the value
> + *
> + * @return a ValueExpression that returns the given instance when evaluated
> + */
> public abstract ValueExpression createValueExpression(Object instance, Class<?> expectedType);
>
> /**
> @@ -202,7 +223,11 @@ public abstract class ExpressionFactory {
> public abstract <T> T coerceToType(Object obj, Class<T> expectedType);
>
> /**
> - * @return This default implementation returns null
> + * Returns an {@link ELResolver} capable of resolving properties on {@link java.io.InputStream}
> + * objects, enabling EL expressions to operate on stream types. This allows expressions to
> + * read data from input streams using standard property navigation syntax.
> + *
> + * @return the StreamELResolver, or {@code null} if not supported by this implementation
> *
> * @since EL 3.0
> */
> @@ -211,7 +236,11 @@ public abstract class ExpressionFactory {
> }
>
> /**
> - * @return This default implementation returns null
> + * Returns a map of function names to {@link java.lang.reflect.Method} objects representing
> + * the standard EL functions that are available by default without explicit registration.
> + * Implementations can override this method to provide a set of built-in functions.
> + *
> + * @return a map of function names to methods, or {@code null} if no default functions are provided
> *
> * @since EL 3.0
> */
> diff --git a/java/jakarta/el/FunctionMapper.java b/java/jakarta/el/FunctionMapper.java
> index 036f12b7d2..fc3fc7c92a 100644
> --- a/java/jakarta/el/FunctionMapper.java
> +++ b/java/jakarta/el/FunctionMapper.java
> @@ -18,8 +18,32 @@ package jakarta.el;
>
> import java.lang.reflect.Method;
>
> +/**
> + * Abstract base class for mapping EL function names to Java {@link java.lang.reflect.Method}
> + * objects. During expression evaluation, the EL implementation uses the FunctionMapper to
> + * resolve function references of the form {@code prefix:functionName} to the corresponding
> + * static Java methods. Implementations maintain a registry of function prefixes and names
> + * mapped to their underlying methods.
> + *
> + * @since EL 2.1
> + */
> public abstract class FunctionMapper {
>
> + /**
> + * Constructs a FunctionMapper. Subclasses should invoke this constructor to initialize
> + * the base mapper state.
> + */
> + public FunctionMapper() {
> + }
> +
> + /**
> + * Resolves a function reference to its corresponding static {@link java.lang.reflect.Method}.
> + *
> + * @param prefix the namespace prefix of the function
> + * @param localName the local name of the function
> + *
> + * @return the {@link Method} object for the resolved function, or {@code null} if not found
> + */
> public abstract Method resolveFunction(String prefix, String localName);
>
> /**
> diff --git a/java/jakarta/el/ImportHandler.java b/java/jakarta/el/ImportHandler.java
> index 2b0725b71e..5885f25730 100644
> --- a/java/jakarta/el/ImportHandler.java
> +++ b/java/jakarta/el/ImportHandler.java
> @@ -28,6 +28,10 @@ import java.util.Set;
> import java.util.concurrent.ConcurrentHashMap;
>
> /**
> + * Manages class and package imports for EL expressions, similar to Java import statements. The ImportHandler resolves
> + * unqualified class names to their fully qualified counterparts, supports static imports, and maintains a set of
> + * standard packages that are automatically available in EL expressions.
> + *
> * @since EL 3.0
> */
> public class ImportHandler {
> @@ -289,11 +293,24 @@ public class ImportHandler {
> private final Map<String,Class<?>> statics = new ConcurrentHashMap<>();
>
>
> + /**
> + * Constructs an ImportHandler with the {@code java.lang} package pre-imported.
> + * The {@code java.lang} package is automatically available in all EL expressions.
> + */
> public ImportHandler() {
> importPackage("java.lang");
> }
>
> -
> + /**
> + * Imports a static field or method so it can be referenced by its simple name in EL
> + * expressions. The argument must be a fully qualified name in the form
> + * {@code className.staticMemberName}. The static member must be public.
> + *
> + * @param name the fully qualified name of the static member to import
> + *
> + * @throws ELException if the name is invalid, the class cannot be found, the static
> + * member does not exist, or the import would be ambiguous
> + */
> public void importStatic(String name) throws ELException {
> int lastPeriod = name.lastIndexOf('.');
>
> @@ -349,6 +366,15 @@ public class ImportHandler {
> }
>
>
> + /**
> + * Imports a class so it can be referenced by its simple name in EL expressions.
> + * The argument must be a fully qualified class name. If the simple name conflicts
> + * with a previously imported class, an exception is thrown.
> + *
> + * @param name the fully qualified class name to import
> + *
> + * @throws ELException if the class name is invalid or conflicts with an existing import
> + */
> public void importClass(String name) throws ELException {
> int lastPeriodIndex = name.lastIndexOf('.');
>
> @@ -366,6 +392,14 @@ public class ImportHandler {
> }
>
>
> + /**
> + * Imports all classes from a package so they can be referenced by their simple names
> + * in EL expressions. Classes from the imported package are resolved during expression
> + * evaluation. If a simple name is ambiguous across multiple imported packages, an
> + * {@link ELException} is thrown at resolution time.
> + *
> + * @param name the package name to import
> + */
> public void importPackage(String name) {
> // Import ambiguity is handled at resolution, not at import
> // Whether the package exists is not checked,
> @@ -377,6 +411,18 @@ public class ImportHandler {
> }
>
>
> + /**
> + * Resolves an unqualified class name to a {@link Class} object by searching the
> + * registered class imports and package imports. The name must not contain a dot.
> + * Results are cached for performance. If the name is ambiguous across multiple
> + * packages, an {@link ELException} is thrown.
> + *
> + * @param name the unqualified class name to resolve
> + *
> + * @return the resolved {@link Class}, or {@code null} if the class cannot be found
> + *
> + * @throws ELException if the class name is ambiguous across imported packages
> + */
> public Class<?> resolveClass(String name) {
> if (name == null || name.contains(".")) {
> return null;
> @@ -445,6 +491,15 @@ public class ImportHandler {
> }
>
>
> + /**
> + * Resolves a statically imported member name to the {@link Class} that declares it.
> + * The name is the simple name of the static field or method as registered by
> + * {@link #importStatic(String)}.
> + *
> + * @param name the simple name of the static member
> + *
> + * @return the declaring {@link Class}, or {@code null} if not found
> + */
> public Class<?> resolveStatic(String name) {
> return statics.get(name);
> }
> diff --git a/java/jakarta/el/LambdaExpression.java b/java/jakarta/el/LambdaExpression.java
> index fe7d9ca233..757a47cf24 100644
> --- a/java/jakarta/el/LambdaExpression.java
> +++ b/java/jakarta/el/LambdaExpression.java
> @@ -21,6 +21,14 @@ import java.util.List;
> import java.util.Map;
> import java.util.Objects;
>
> +/**
> + * Represents a lambda expression in EL. A lambda expression has a list of formal parameters
> + * and a body expression. When invoked, the lambda binds the actual arguments to its formal
> + * parameters and evaluates the body expression within a scoped {@link ELContext}. Lambda
> + * expressions support nesting, with inner lambdas having access to outer lambda arguments.
> + *
> + * @since EL 3.0
> + */
> public class LambdaExpression {
>
> private final List<String> formalParameters;
> @@ -28,16 +36,42 @@ public class LambdaExpression {
> private final Map<String,Object> nestedArguments = new HashMap<>();
> private ELContext context = null;
>
> + /**
> + * Constructs a LambdaExpression with the given formal parameters and body expression.
> + *
> + * @param formalParameters the list of formal parameter names for the lambda
> + * @param expression the body expression to evaluate when the lambda is invoked
> + */
> public LambdaExpression(List<String> formalParameters, ValueExpression expression) {
> this.formalParameters = formalParameters;
> this.expression = expression;
>
> }
>
> + /**
> + * Sets the {@link ELContext} to be used when this lambda is invoked without an explicit
> + * context argument. This is called automatically when the lambda is coerced to a
> + * functional interface type.
> + *
> + * @param context the ELContext to use for evaluation
> + */
> public void setELContext(ELContext context) {
> this.context = context;
> }
>
> + /**
> + * Invokes the lambda expression with the given arguments in the specified EL context.
> + * The formal parameters are bound to the corresponding arguments, and the body
> + * expression is evaluated within a lambda scope. If the result is another lambda,
> + * the current arguments are made available to the nested lambda.
> + *
> + * @param context the ELContext in which to evaluate the lambda
> + * @param args the actual arguments to bind to the formal parameters
> + *
> + * @return the result of evaluating the lambda body expression
> + *
> + * @throws ELException if the number of arguments is less than the number of formal parameters
> + */
> @SuppressWarnings("null") // args[i] can't be null due to earlier checks
> public Object invoke(ELContext context, Object... args) throws ELException {
>
> @@ -81,6 +115,17 @@ public class LambdaExpression {
> }
> }
>
> + /**
> + * Invokes the lambda expression with the given arguments using the EL context set by
> + * {@link #setELContext(ELContext)}. This is a convenience method for use when the
> + * lambda has been assigned to a functional interface variable.
> + *
> + * @param args the actual arguments to bind to the formal parameters
> + *
> + * @return the result of evaluating the lambda body expression
> + *
> + * @throws ELException if the number of arguments is less than the number of formal parameters
> + */
> public Object invoke(Object... args) {
> return invoke(context, args);
> }
> diff --git a/java/jakarta/el/ListELResolver.java b/java/jakarta/el/ListELResolver.java
> index 13c73e16f6..34b0b15267 100644
> --- a/java/jakarta/el/ListELResolver.java
> +++ b/java/jakarta/el/ListELResolver.java
> @@ -21,6 +21,14 @@ import java.util.Collections;
> import java.util.List;
> import java.util.Objects;
>
> +/**
> + * An {@link ELResolver} that resolves properties on {@link java.util.List} objects using
> + * integer indices. When the base object is a {@code List}, the property is coerced to an
> + * integer and used as the list index. This resolver supports read and write operations,
> + * and can be configured as read-only to prevent modification of list elements.
> + *
> + * @since EL 2.1
> + */
> public class ListELResolver extends ELResolver {
>
> private final boolean readOnly;
> @@ -29,10 +37,20 @@ public class ListELResolver extends ELResolver {
> // classes. Java 9 + so a back-port would require JreCompat.
> private static final Class<?> UNMODIFIABLE = Collections.unmodifiableList(new ArrayList<>()).getClass();
>
> + /**
> + * Constructs a ListELResolver that allows both read and write operations on lists.
> + */
> public ListELResolver() {
> this.readOnly = false;
> }
>
> + /**
> + * Constructs a ListELResolver with the specified read-only setting. When read-only
> + * is {@code true}, attempts to set values on list elements will throw a
> + * {@link PropertyNotWritableException}.
> + *
> + * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
> + */
> public ListELResolver(boolean readOnly) {
> this.readOnly = readOnly;
> }
> diff --git a/java/jakarta/el/MapELResolver.java b/java/jakarta/el/MapELResolver.java
> index 973d2ee35d..32272a8916 100644
> --- a/java/jakarta/el/MapELResolver.java
> +++ b/java/jakarta/el/MapELResolver.java
> @@ -21,16 +21,34 @@ import java.util.HashMap;
> import java.util.Map;
> import java.util.Objects;
>
> +/**
> + * An {@link ELResolver} that resolves properties on {@link java.util.Map} objects using
> + * the property as a map key. When the base object is a {@code Map}, the property is used
> + * directly as the key to look up or set values. This resolver supports read and write
> + * operations, and can be configured as read-only to prevent modification of map entries.
> + *
> + * @since EL 2.1
> + */
> public class MapELResolver extends ELResolver {
>
> private static final Class<?> UNMODIFIABLE = Collections.unmodifiableMap(new HashMap<>()).getClass();
>
> private final boolean readOnly;
>
> + /**
> + * Constructs a MapELResolver that allows both read and write operations on maps.
> + */
> public MapELResolver() {
> this.readOnly = false;
> }
>
> + /**
> + * Constructs a MapELResolver with the specified read-only setting. When read-only
> + * is {@code true}, attempts to set values on map entries will throw a
> + * {@link PropertyNotWritableException}.
> + *
> + * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
> + */
> public MapELResolver(boolean readOnly) {
> this.readOnly = readOnly;
> }
> diff --git a/java/jakarta/el/MethodExpression.java b/java/jakarta/el/MethodExpression.java
> index 715cf43bb9..876619b07f 100644
> --- a/java/jakarta/el/MethodExpression.java
> +++ b/java/jakarta/el/MethodExpression.java
> @@ -18,12 +18,24 @@ package jakarta.el;
>
> import java.io.Serial;
>
> +/**
> + * Represents a compiled EL method expression. A MethodExpression is the result of compiling an EL expression
> + * that resolves to a method, and can be invoked at a later time with a given set of parameters.
> + */
> public abstract class MethodExpression extends Expression {
>
> @Serial
> private static final long serialVersionUID = 8163925562047324656L;
>
> /**
> + * Constructs a MethodExpression.
> + */
> + public MethodExpression() {
> + }
> +
> + /**
> + * Returns information about the method that this expression resolves to.
> + *
> * @param context The EL context for this evaluation
> *
> * @return Information about the method that this expression resolves to
> @@ -37,6 +49,8 @@ public abstract class MethodExpression extends Expression {
> public abstract MethodInfo getMethodInfo(ELContext context);
>
> /**
> + * Invokes the method that this expression resolves to with the given parameters.
> + *
> * @param context The EL context for this evaluation
> * @param params The parameters with which to invoke this method expression
> *
> @@ -52,6 +66,8 @@ public abstract class MethodExpression extends Expression {
> public abstract Object invoke(ELContext context, Object[] params);
>
> /**
> + * Returns whether the parameters for the method invocation are provided by the expression or by the container.
> + *
> * @return This default implementation always returns <code>false</code>
> *
> * @since EL 3.0
> diff --git a/java/jakarta/el/MethodInfo.java b/java/jakarta/el/MethodInfo.java
> index 3dbcfe75a1..034433d303 100644
> --- a/java/jakarta/el/MethodInfo.java
> +++ b/java/jakarta/el/MethodInfo.java
> @@ -18,28 +18,57 @@ package jakarta.el;
>
> import java.util.Arrays;
>
> +/**
> + * Holds metadata about a method that an EL method expression resolves to, including the method name,
> + * return type, and parameter types.
> + */
> public class MethodInfo {
>
> + /** The name of the method. */
> private final String name;
>
> + /** The parameter types of the method. */
> private final Class<?>[] paramTypes;
>
> + /** The return type of the method. */
> private final Class<?> returnType;
>
> + /**
> + * Constructs a MethodInfo with the given name, return type, and parameter types.
> + *
> + * @param name The name of the method
> + * @param returnType The return type of the method
> + * @param paramTypes The parameter types of the method
> + */
> public MethodInfo(String name, Class<?> returnType, Class<?>[] paramTypes) {
> this.name = name;
> this.returnType = returnType;
> this.paramTypes = paramTypes;
> }
>
> + /**
> + * Returns the name of the method.
> + *
> + * @return the method name
> + */
> public String getName() {
> return this.name;
> }
>
> + /**
> + * Returns the return type of the method.
> + *
> + * @return the return type
> + */
> public Class<?> getReturnType() {
> return this.returnType;
> }
>
> + /**
> + * Returns the parameter types of the method.
> + *
> + * @return the parameter types
> + */
> public Class<?>[] getParamTypes() {
> return this.paramTypes;
> }
> diff --git a/java/jakarta/el/MethodNotFoundException.java b/java/jakarta/el/MethodNotFoundException.java
> index 8a92baf0f3..7232656c97 100644
> --- a/java/jakarta/el/MethodNotFoundException.java
> +++ b/java/jakarta/el/MethodNotFoundException.java
> @@ -18,23 +18,45 @@ package jakarta.el;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when a method referenced in an EL expression cannot be found on the target object.
> + */
> public class MethodNotFoundException extends ELException {
>
> @Serial
> private static final long serialVersionUID = -3631968116081480328L;
>
> + /**
> + * Constructs a MethodNotFoundException with no detail message.
> + */
> public MethodNotFoundException() {
> super();
> }
>
> + /**
> + * Constructs a MethodNotFoundException with the specified detail message.
> + *
> + * @param message the detail message
> + */
> public MethodNotFoundException(String message) {
> super(message);
> }
>
> + /**
> + * Constructs a MethodNotFoundException with the specified cause.
> + *
> + * @param cause the cause of this exception
> + */
> public MethodNotFoundException(Throwable cause) {
> super(cause);
> }
>
> + /**
> + * Constructs a MethodNotFoundException with the specified detail message and cause.
> + *
> + * @param message the detail message
> + * @param cause the cause of this exception
> + */
> public MethodNotFoundException(String message, Throwable cause) {
> super(message, cause);
> }
> diff --git a/java/jakarta/el/MethodReference.java b/java/jakarta/el/MethodReference.java
> index 6f86ffcbea..86b008faac 100644
> --- a/java/jakarta/el/MethodReference.java
> +++ b/java/jakarta/el/MethodReference.java
> @@ -26,12 +26,24 @@ import java.util.Arrays;
> */
> public class MethodReference {
>
> + /** The base object on which the method will be invoked. */
> private final Object base;
> + /** The method information. */
> private final MethodInfo methodInfo;
> + /** The annotations on the method. */
> private final Annotation[] annotations;
> + /** The evaluated parameter values for the method invocation. */
> private final Object[] evaluatedParameters;
>
>
> + /**
> + * Constructs a MethodReference with the given base object, method info, annotations, and evaluated parameters.
> + *
> + * @param base The base object on which the method will be invoked
> + * @param methodInfo Information about the method
> + * @param annotations The annotations on the method
> + * @param evaluatedParameters The evaluated parameter values for the method invocation
> + */
> public MethodReference(Object base, MethodInfo methodInfo, Annotation[] annotations, Object[] evaluatedParameters) {
> this.base = base;
> this.methodInfo = methodInfo;
> diff --git a/java/jakarta/el/OptionalELResolver.java b/java/jakarta/el/OptionalELResolver.java
> index 9600e1abca..4b59e62d37 100644
> --- a/java/jakarta/el/OptionalELResolver.java
> +++ b/java/jakarta/el/OptionalELResolver.java
> @@ -30,6 +30,12 @@ import java.util.Optional;
> */
> public class OptionalELResolver extends ELResolver {
>
> + /**
> + * Constructs an OptionalELResolver.
> + */
> + public OptionalELResolver() {
> + }
> +
> /**
> * {@inheritDoc}
> *
> diff --git a/java/jakarta/el/PropertyNotFoundException.java b/java/jakarta/el/PropertyNotFoundException.java
> index 45aff2e48b..7f8aa90598 100644
> --- a/java/jakarta/el/PropertyNotFoundException.java
> +++ b/java/jakarta/el/PropertyNotFoundException.java
> @@ -18,23 +18,50 @@ package jakarta.el;
>
> import java.io.Serial;
>
> +/**
> + * Exception thrown when a property is not found during EL evaluation.
> + * <p>
> + * This exception is raised when an expression attempts to access a property
> + * that does not exist on the target object.
> + *
> + * @since EL 2.1
> + */
> public class PropertyNotFoundException extends ELException {
>
> @Serial
> private static final long serialVersionUID = -3799200961303506745L;
>
> + /**
> + * Constructs a new instance with no detail message or cause.
> + */
> public PropertyNotFoundException() {
> super();
> }
>
> + /**
> + * Constructs a new instance with the specified detail message and no cause.
> + *
> + * @param message the detail message
> + */
> public PropertyNotFoundException(String message) {
> super(message);
> }
>
> + /**
> + * Constructs a new instance with the specified cause and no detail message.
> + *
> + * @param cause the underlying cause
> + */
> public PropertyNotFoundException(Throwable cause) {
> super(cause);
> }
>
> + /**
> + * Constructs a new instance with the specified detail message and cause.
> + *
> + * @param message the detail message
> + * @param cause the underlying cause
> + */
> public PropertyNotFoundException(String message, Throwable cause) {
> super(message, cause);
> }
> diff --git a/java/jakarta/el/PropertyNotWritableException.java b/java/jakarta/el/PropertyNotWritableException.java
> index 58f28e9c34..14b53ba4ca 100644
> --- a/java/jakarta/el/PropertyNotWritableException.java
> +++ b/java/jakarta/el/PropertyNotWritableException.java
> @@ -18,23 +18,50 @@ package jakarta.el;
>
> import java.io.Serial;
>
> +/**
> + * Exception thrown when an EL expression attempts to write to a read-only property.
> + * <p>
> + * This exception is raised during setValue operations when the target property
> + * exists but cannot be modified.
> + *
> + * @since EL 2.1
> + */
> public class PropertyNotWritableException extends ELException {
>
> @Serial
> private static final long serialVersionUID = 827987155471214717L;
>
> + /**
> + * Constructs a new instance with no detail message or cause.
> + */
> public PropertyNotWritableException() {
> super();
> }
>
> + /**
> + * Constructs a new instance with the specified detail message and no cause.
> + *
> + * @param message the detail message
> + */
> public PropertyNotWritableException(String message) {
> super(message);
> }
>
> + /**
> + * Constructs a new instance with the specified cause and no detail message.
> + *
> + * @param cause the underlying cause
> + */
> public PropertyNotWritableException(Throwable cause) {
> super(cause);
> }
>
> + /**
> + * Constructs a new instance with the specified detail message and cause.
> + *
> + * @param message the detail message
> + * @param cause the underlying cause
> + */
> public PropertyNotWritableException(String message, Throwable cause) {
> super(message, cause);
> }
> diff --git a/java/jakarta/el/RecordELResolver.java b/java/jakarta/el/RecordELResolver.java
> index 37c0cc64a3..01b4dc6792 100644
> --- a/java/jakarta/el/RecordELResolver.java
> +++ b/java/jakarta/el/RecordELResolver.java
> @@ -35,6 +35,13 @@ import java.util.Objects;
> */
> public class RecordELResolver extends ELResolver {
>
> + /**
> + * Constructs a new instance of the resolver.
> + */
> + public RecordELResolver() {
> + super();
> + }
> +
> /**
> * If the base object is an instance of {@link Record}, returns the value of the given field of this {@link Record}.
> * <p>
> diff --git a/java/jakarta/el/ResourceBundleELResolver.java b/java/jakarta/el/ResourceBundleELResolver.java
> index 62e9fd6729..2ae2ae054e 100644
> --- a/java/jakarta/el/ResourceBundleELResolver.java
> +++ b/java/jakarta/el/ResourceBundleELResolver.java
> @@ -20,8 +20,26 @@ import java.util.MissingResourceException;
> import java.util.Objects;
> import java.util.ResourceBundle;
>
> +/**
> + * EL resolver for resource bundle properties.
> + * <p>
> + * This resolver handles base objects of type {@link ResourceBundle}. It accepts
> + * any non-null object as a property, coerces it to a String, and uses it to
> + * look up the corresponding message in the resource bundle. If the key is not
> + * found, the resolver returns a placeholder string of the form {@code ???key???}.
> + * Resource bundles are always read-only.
> + * <p>
> + * {@code ELResolver}s are combined using {@link CompositeELResolver}s to define
> + * rich semantics for evaluating an expression. See the javadocs for
> + * {@link ELResolver} for details.
> + *
> + * @since EL 2.1
> + */
> public class ResourceBundleELResolver extends ELResolver {
>
> + /**
> + * Constructs a new instance of the resolver.
> + */
> public ResourceBundleELResolver() {
> super();
> }
> diff --git a/java/jakarta/el/StandardELContext.java b/java/jakarta/el/StandardELContext.java
> index 17c5f44b3d..ce2ed86605 100644
> --- a/java/jakarta/el/StandardELContext.java
> +++ b/java/jakarta/el/StandardELContext.java
> @@ -21,6 +21,10 @@ import java.util.HashMap;
> import java.util.Map;
>
> /**
> + * Standard implementation of {@link ELContext} that provides a complete EL resolution environment. It maintains a
> + * composite resolver chain, variable mapper, function mapper, and supports custom resolvers and local beans. This is
> + * the default context implementation used by {@link ELProcessor}.
> + *
> * @since EL 3.0
> */
> public class StandardELContext extends ELContext {
> @@ -33,6 +37,14 @@ public class StandardELContext extends ELContext {
> private final Map<String,Object> localBeans = new HashMap<>();
>
>
> + /**
> + * Constructs a new instance backed by the given expression factory.
> + * <p>
> + * Initializes the standard resolver chain with built-in resolvers and
> + * a function mapper populated from the factory's initial function map.
> + *
> + * @param factory the expression factory providing the initial resolver and function configuration
> + */
> public StandardELContext(ExpressionFactory factory) {
> wrappedContext = null;
> variableMapper = new StandardVariableMapper();
> @@ -57,6 +69,14 @@ public class StandardELContext extends ELContext {
> standardResolver.add(new BeanELResolver());
> }
>
> + /**
> + * Constructs a new instance that wraps the given context.
> + * <p>
> + * The variable mapper, function mapper, and EL resolver from the wrapped
> + * context are used, with additional standard resolvers prepended.
> + *
> + * @param context the context to wrap
> + */
> public StandardELContext(ELContext context) {
> wrappedContext = context;
> variableMapper = context.getVariableMapper();
> @@ -94,6 +114,15 @@ public class StandardELContext extends ELContext {
> return standardResolver;
> }
>
> + /**
> + * Adds a custom EL resolver to the resolver chain.
> + * <p>
> + * Custom resolvers are inserted after the bean name resolver and before
> + * the standard resolvers, allowing them to intercept resolution before
> + * the built-in resolvers are consulted.
> + *
> + * @param resolver the resolver to add
> + */
> public void addELResolver(ELResolver resolver) {
> customResolvers.add(resolver);
> }
> diff --git a/java/jakarta/el/StaticFieldELResolver.java b/java/jakarta/el/StaticFieldELResolver.java
> index c69e306005..d77e0c733a 100644
> --- a/java/jakarta/el/StaticFieldELResolver.java
> +++ b/java/jakarta/el/StaticFieldELResolver.java
> @@ -24,10 +24,21 @@ import java.lang.reflect.Modifier;
> import java.util.Objects;
>
> /**
> + * ELResolver that resolves static fields and invokes static methods on classes. This resolver handles expressions
> + * where the base is an {@link ELClass} and the property is a {@link String} representing a field or method name.
> + * Static fields are read-only.
> + *
> * @since EL 3.0
> */
> public class StaticFieldELResolver extends ELResolver {
>
> + /**
> + * Constructs a new instance of the resolver.
> + */
> + public StaticFieldELResolver() {
> + super();
> + }
> +
> @Override
> public Object getValue(ELContext context, Object base, Object property) {
> Objects.requireNonNull(context);
> diff --git a/java/jakarta/el/TypeConverter.java b/java/jakarta/el/TypeConverter.java
> index 532543d3da..acc2acf370 100644
> --- a/java/jakarta/el/TypeConverter.java
> +++ b/java/jakarta/el/TypeConverter.java
> @@ -17,10 +17,21 @@
> package jakarta.el;
>
> /**
> + * Base class for ELResolvers that perform type conversion. A TypeConverter is an ELResolver that specializes in
> + * converting objects from one type to another via the {@link #convertToType} method. Standard property resolution
> + * methods return {@code null} or no-op, as this resolver is focused solely on type conversion.
> + *
> * @since EL 3.0
> */
> public abstract class TypeConverter extends ELResolver {
>
> + /**
> + * Constructs a new instance of the type converter.
> + */
> + public TypeConverter() {
> + super();
> + }
> +
> @Override
> public Object getValue(ELContext context, Object base, Object property) {
> return null;
> diff --git a/java/jakarta/el/ValueExpression.java b/java/jakarta/el/ValueExpression.java
> index 892c96128c..2db42cdbca 100644
> --- a/java/jakarta/el/ValueExpression.java
> +++ b/java/jakarta/el/ValueExpression.java
> @@ -18,12 +18,29 @@ package jakarta.el;
>
> import java.io.Serial;
>
> +/**
> + * Represents a parsed EL expression that can be evaluated to produce a value.
> + * <p>
> + * A value expression is created by parsing an EL expression string and can be
> + * evaluated multiple times in different contexts. It supports reading values,
> + * writing values, and introspecting the expression's type and mutability.
> + *
> + * @since EL 2.1
> + */
> public abstract class ValueExpression extends Expression {
>
> @Serial
> private static final long serialVersionUID = 8577809572381654673L;
>
> /**
> + * Constructs a new value expression.
> + */
> + public ValueExpression() {
> + }
> +
> + /**
> + * Evaluates this expression and returns the result.
> + *
> * @param <T> The expected type for the result of evaluating this value expression
> * @param context The EL context for this evaluation
> *
> @@ -37,6 +54,8 @@ public abstract class ValueExpression extends Expression {
> public abstract <T> T getValue(ELContext context);
>
> /**
> + * Sets the value of the property referenced by this expression.
> + *
> * @param context The EL context for this evaluation
> * @param value The value to set the property to which this value expression refers
> *
> @@ -49,6 +68,8 @@ public abstract class ValueExpression extends Expression {
> public abstract void setValue(ELContext context, Object value);
>
> /**
> + * Determines whether the property referenced by this expression is read-only.
> + *
> * @param context The EL context for this evaluation
> *
> * @return <code>true</code> if this expression is read only otherwise <code>false</code>
> @@ -61,6 +82,8 @@ public abstract class ValueExpression extends Expression {
> public abstract boolean isReadOnly(ELContext context);
>
> /**
> + * Returns the type of the result produced by evaluating this expression.
> + *
> * @param context The EL context for this evaluation
> *
> * @return The type of the result of this value expression
> @@ -72,9 +95,19 @@ public abstract class ValueExpression extends Expression {
> */
> public abstract Class<?> getType(ELContext context);
>
> + /**
> + * Returns the expected type of the result of this expression.
> + *
> + * @return The expected result type, or {@code Object.class} if no specific type is expected
> + */
> public abstract Class<?> getExpectedType();
>
> /**
> + * Returns a reference to the resolved property for this expression.
> + * <p>
> + * This default implementation always returns {@code null}. Subclasses should
> + * override this method to provide the resolved base object and property.
> + *
> * @param context The EL context for this evaluation
> *
> * @return This default implementation always returns <code>null</code>
> diff --git a/java/jakarta/el/ValueReference.java b/java/jakarta/el/ValueReference.java
> index b7b2cee9ed..53090d7288 100644
> --- a/java/jakarta/el/ValueReference.java
> +++ b/java/jakarta/el/ValueReference.java
> @@ -20,6 +20,10 @@ import java.io.Serial;
> import java.io.Serializable;
>
> /**
> + * Holds a reference to a resolved property, consisting of a base object and a property identifier. This class is
> + * used to capture the result of property resolution during EL evaluation, allowing the caller to perform additional
> + * operations on the resolved property.
> + *
> * @since EL 2.2
> */
> public class ValueReference implements Serializable {
> @@ -27,18 +31,37 @@ public class ValueReference implements Serializable {
> @Serial
> private static final long serialVersionUID = 1L;
>
> + /** The base object on which the property was resolved. */
> private final Object base;
> +
> + /** The property identifier. */
> private final Object property;
>
> + /**
> + * Constructs a new value reference with the given base object and property.
> + *
> + * @param base The base object on which the property was resolved
> + * @param property The property identifier
> + */
> public ValueReference(Object base, Object property) {
> this.base = base;
> this.property = property;
> }
>
> + /**
> + * Returns the base object on which the property was resolved.
> + *
> + * @return The base object
> + */
> public Object getBase() {
> return base;
> }
>
> + /**
> + * Returns the property identifier.
> + *
> + * @return The property identifier
> + */
> public Object getProperty() {
> return property;
> }
> diff --git a/java/jakarta/el/VariableMapper.java b/java/jakarta/el/VariableMapper.java
> index 79018e0f0d..8d41c6b7e5 100644
> --- a/java/jakarta/el/VariableMapper.java
> +++ b/java/jakarta/el/VariableMapper.java
> @@ -17,11 +17,34 @@
> package jakarta.el;
>
> /**
> - *
> + * Manages the mapping between variable names and their corresponding {@link ValueExpression} instances within an
> + * {@link ELContext}. Variable mappings allow EL expressions to reference named variables that resolve to computed
> + * values.
> */
> public abstract class VariableMapper {
>
> + /**
> + * Default constructor for subclasses.
> + */
> + public VariableMapper() {
> + }
> +
> + /**
> + * Resolves a variable name to its corresponding ValueExpression.
> + *
> + * @param variable the name of the variable to resolve
> + *
> + * @return the ValueExpression for the variable, or {@code null} if not found
> + */
> public abstract ValueExpression resolveVariable(String variable);
>
> + /**
> + * Sets or removes a variable mapping.
> + *
> + * @param variable the name of the variable
> + * @param expression the ValueExpression to associate with the variable, or {@code null} to remove the mapping
> + *
> + * @return the previous ValueExpression for the variable, or {@code null} if there was no mapping
> + */
> public abstract ValueExpression setVariable(String variable, ValueExpression expression);
> }
> diff --git a/java/jakarta/mail/Authenticator.java b/java/jakarta/mail/Authenticator.java
> index 65866750ef..3896516877 100644
> --- a/java/jakarta/mail/Authenticator.java
> +++ b/java/jakarta/mail/Authenticator.java
> @@ -16,7 +16,25 @@
> */
> package jakarta.mail;
>
> +/**
> + * Abstract base class for providing user authentication when establishing network connections. Subclasses override
> + * {@link #getPasswordAuthentication} to return the appropriate credentials. This class is part of the Jakarta Mail
> + * API and follows the pattern defined by {@link java.net.Authenticator}.
> + */
> public class Authenticator {
> +
> + /**
> + * Default constructor for subclasses.
> + */
> + public Authenticator() {
> + }
> +
> + /**
> + * Returns the password authentication information for the current request. The default implementation returns
> + * {@code null}. Subclasses should override this method to provide actual credentials.
> + *
> + * @return the PasswordAuthentication object, or {@code null} if no authentication is available
> + */
> protected PasswordAuthentication getPasswordAuthentication() {
> return null;
> }
> diff --git a/java/jakarta/mail/PasswordAuthentication.java b/java/jakarta/mail/PasswordAuthentication.java
> index 7be7b29e85..a76f8b7909 100644
> --- a/java/jakarta/mail/PasswordAuthentication.java
> +++ b/java/jakarta/mail/PasswordAuthentication.java
> @@ -16,8 +16,20 @@
> */
> package jakarta.mail;
>
> +/**
> + * Stores username and password credentials for mail authentication. This class follows the pattern defined by
> + * {@link java.net.PasswordAuthentication} and is used with {@link Authenticator} to provide credentials when
> + * establishing mail connections.
> + */
> @SuppressWarnings("unused") // Dummy implementation
> public class PasswordAuthentication {
> +
> + /**
> + * Constructs a PasswordAuthentication with the given user and password.
> + *
> + * @param user the username
> + * @param password the password
> + */
> public PasswordAuthentication(String user, String password) {
> // Dummy implementation
> }
> diff --git a/java/jakarta/mail/Session.java b/java/jakarta/mail/Session.java
> index 87ff869d3b..35f221afff 100644
> --- a/java/jakarta/mail/Session.java
> +++ b/java/jakarta/mail/Session.java
> @@ -18,12 +18,34 @@ package jakarta.mail;
>
> import java.util.Properties;
>
> +/**
> + * Represents a mail session configuration.
> + */
> @SuppressWarnings("unused") // Dummy implementation
> public class Session {
> + /**
> + * Default constructor.
> + */
> + public Session() {
> + }
> +
> + /**
> + * Returns a Session object with the given properties and authenticator.
> + *
> + * @param props the session properties
> + * @param auth the authenticator
> + * @return the mail session
> + */
> public static Session getInstance(Properties props, Authenticator auth) {
> return null;
> }
>
> + /**
> + * Returns a Session object with the given properties.
> + *
> + * @param props the session properties
> + * @return the mail session
> + */
> public static Session getInstance(Properties props) {
> return null;
> }
> diff --git a/java/jakarta/mail/internet/InternetAddress.java b/java/jakarta/mail/internet/InternetAddress.java
> index aa1ce3859e..5d766f5e4d 100644
> --- a/java/jakarta/mail/internet/InternetAddress.java
> +++ b/java/jakarta/mail/internet/InternetAddress.java
> @@ -16,8 +16,19 @@
> */
> package jakarta.mail.internet;
>
> +/**
> + * Represents an Internet email address as defined by RFC 822.
> + * An Internet address consists of an optional personal name and
> + * an address string in the form of local-part@domain.
> + */
> @SuppressWarnings("unused") // Dummy implementation
> public class InternetAddress {
> + /**
> + * Constructs an InternetAddress from the specified address string.
> + * The address string may optionally include a personal name portion.
> + *
> + * @param from the email address string to parse
> + */
> public InternetAddress(String from) {
> // Dummy implementation
> }
> diff --git a/java/jakarta/mail/internet/MimeMessage.java b/java/jakarta/mail/internet/MimeMessage.java
> index 39644f0509..3fae2b288c 100644
> --- a/java/jakarta/mail/internet/MimeMessage.java
> +++ b/java/jakarta/mail/internet/MimeMessage.java
> @@ -18,16 +18,35 @@ package jakarta.mail.internet;
>
> import jakarta.mail.Session;
>
> +/**
> + * Represents a MIME message in the Jakarta Mail API.
> + * Provides methods for setting message headers such as sender and subject.
> + */
> @SuppressWarnings("unused") // Dummy implementation
> public class MimeMessage implements MimePart {
> + /**
> + * Constructs a MimeMessage with the given Session.
> + *
> + * @param session the mail session used to create this message
> + */
> public MimeMessage(Session session) {
> // Dummy implementation
> }
>
> + /**
> + * Sets the InternetAddress of the message sender.
> + *
> + * @param from the InternetAddress of the sender
> + */
> public void setFrom(InternetAddress from) {
> // Dummy implementation
> }
>
> + /**
> + * Sets the subject of the message.
> + *
> + * @param subject the subject string
> + */
> public void setSubject(String subject) {
> // Dummy implementation
> }
> diff --git a/java/jakarta/mail/internet/MimePart.java b/java/jakarta/mail/internet/MimePart.java
> index 7591634fae..0be69d33e6 100644
> --- a/java/jakarta/mail/internet/MimePart.java
> +++ b/java/jakarta/mail/internet/MimePart.java
> @@ -16,6 +16,10 @@
> */
> package jakarta.mail.internet;
>
> +/**
> + * Represents a part of a MIME message in the Jakarta Mail API.
> + * A MimePart can contain content and headers for a single MIME entity.
> + */
> public interface MimePart {
> // Dummy implementation
> }
> diff --git a/java/jakarta/mail/internet/MimePartDataSource.java b/java/jakarta/mail/internet/MimePartDataSource.java
> index a86bae55ea..17b946b53a 100644
> --- a/java/jakarta/mail/internet/MimePartDataSource.java
> +++ b/java/jakarta/mail/internet/MimePartDataSource.java
> @@ -16,8 +16,17 @@
> */
> package jakarta.mail.internet;
>
> +/**
> + * Provides a DataSource representation for a MimePart.
> + * Wraps a MimePart so it can be used where a DataSource is required.
> + */
> @SuppressWarnings("unused") // Dummy implementation
> public class MimePartDataSource {
> + /**
> + * Constructs a MimePartDataSource wrapping the given MimePart.
> + *
> + * @param part the MimePart to wrap
> + */
> public MimePartDataSource(MimePart part) {
> // Dummy implementation
> }
> diff --git a/java/jakarta/persistence/PersistenceContext.java b/java/jakarta/persistence/PersistenceContext.java
> index 78ece9e615..c0963ab44c 100644
> --- a/java/jakarta/persistence/PersistenceContext.java
> +++ b/java/jakarta/persistence/PersistenceContext.java
> @@ -21,17 +21,45 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Specifies the entity manager for use with an entity bean or other managed class.
> + * Used to inject a persistence context into a Jakarta EE managed component.
> + */
> @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface PersistenceContext {
> + /**
> + * The name used to look up the persistence context.
> + *
> + * @return the persistence context name
> + */
> String name() default "";
>
> + /**
> + * The unit name of the persistence unit to associate with the persistence context.
> + *
> + * @return the persistence unit name
> + */
> String unitName() default "";
>
> + /**
> + * The type of the persistence context.
> + *
> + * @return the persistence context type
> + */
> PersistenceContextType type() default PersistenceContextType.TRANSACTION;
>
> + /**
> + * Properties used to configure the persistence context.
> + *
> + * @return the configuration properties
> + */
> PersistenceProperty[] properties() default {};
>
> + /**
> + * The synchronization type of the persistence context with the transaction.
> + *
> + * @return the synchronization type
> + */
> SynchronizationType synchronization() default SynchronizationType.SYNCHRONIZED;
> }
> diff --git a/java/jakarta/persistence/PersistenceContextType.java b/java/jakarta/persistence/PersistenceContextType.java
> index 0e54e3c1ad..9f4af89442 100644
> --- a/java/jakarta/persistence/PersistenceContextType.java
> +++ b/java/jakarta/persistence/PersistenceContextType.java
> @@ -16,7 +16,21 @@
> */
> package jakarta.persistence;
>
> +/**
> + * Defines the type of persistence context.
> + */
> public enum PersistenceContextType {
> + /**
> + * The default persistence context type.
> + * The entity manager is tied to the current transaction and is automatically
> + * closed when the transaction completes.
> + */
> TRANSACTION,
> +
> + /**
> + * An extended persistence context type.
> + * The entity manager spans multiple transactions and remains open
> + * until explicitly closed by the application.
> + */
> EXTENDED
> -}
> \ No newline at end of file
> +}
> diff --git a/java/jakarta/persistence/PersistenceContexts.java b/java/jakarta/persistence/PersistenceContexts.java
> index 671d117c7c..ab3f2d49ce 100644
> --- a/java/jakarta/persistence/PersistenceContexts.java
> +++ b/java/jakarta/persistence/PersistenceContexts.java
> @@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple PersistenceContext annotations for injection into a single component.
> + */
> @Target(ElementType.TYPE)
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface PersistenceContexts {
> + /**
> + * The array of PersistenceContext annotations.
> + *
> + * @return the persistence contexts
> + */
> PersistenceContext[] value();
> }
> diff --git a/java/jakarta/persistence/PersistenceProperty.java b/java/jakarta/persistence/PersistenceProperty.java
> index 3ed05e1982..8c39f8a41b 100644
> --- a/java/jakarta/persistence/PersistenceProperty.java
> +++ b/java/jakarta/persistence/PersistenceProperty.java
> @@ -20,11 +20,24 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Specifies a property for configuring a persistence context or persistence unit.
> + * Used within the properties element of PersistenceContext or PersistenceUnit annotations.
> + */
> @Target({})
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface PersistenceProperty {
> + /**
> + * The name of the property.
> + *
> + * @return the property name
> + */
> String name();
>
> + /**
> + * The value of the property.
> + *
> + * @return the property value
> + */
> String value();
> }
> diff --git a/java/jakarta/persistence/PersistenceUnit.java b/java/jakarta/persistence/PersistenceUnit.java
> index 0580f11112..5d72ed565a 100644
> --- a/java/jakarta/persistence/PersistenceUnit.java
> +++ b/java/jakarta/persistence/PersistenceUnit.java
> @@ -21,11 +21,25 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Specifies a persistence unit for use with an entity bean or other managed class. Used to inject an
> + * EntityManagerFactory into a Jakarta EE managed component.
> + */
> @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface PersistenceUnit {
> +
> + /**
> + * The name used to look up the EntityManagerFactory.
> + *
> + * @return the lookup name
> + */
> String name() default "";
>
> + /**
> + * The unit name of the persistence unit.
> + *
> + * @return the persistence unit name
> + */
> String unitName() default "";
> }
> diff --git a/java/jakarta/persistence/PersistenceUnits.java b/java/jakarta/persistence/PersistenceUnits.java
> index 3da4da578e..d1260eb30a 100644
> --- a/java/jakarta/persistence/PersistenceUnits.java
> +++ b/java/jakarta/persistence/PersistenceUnits.java
> @@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple PersistenceUnit annotations for injection into a single component.
> + */
> @Target(ElementType.TYPE)
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface PersistenceUnits {
> + /**
> + * The array of PersistenceUnit annotations.
> + *
> + * @return the persistence units
> + */
> PersistenceUnit[] value();
> }
> diff --git a/java/jakarta/persistence/SynchronizationType.java b/java/jakarta/persistence/SynchronizationType.java
> index b1d5c1acc5..40ad6bf5ac 100644
> --- a/java/jakarta/persistence/SynchronizationType.java
> +++ b/java/jakarta/persistence/SynchronizationType.java
> @@ -16,7 +16,16 @@
> */
> package jakarta.persistence;
>
> +/**
> + * Specifies the synchronization type of an entity manager with JTA transactions.
> + */
> public enum SynchronizationType {
> + /**
> + * The entity manager participates in the current JTA transaction.
> + */
> SYNCHRONIZED,
> + /**
> + * The entity manager does not participate in the current JTA transaction.
> + */
> UNSYNCHRONIZED
> }
> diff --git a/java/jakarta/security/auth/message/AuthException.java b/java/jakarta/security/auth/message/AuthException.java
> index f5a71e44fc..40cd5a47cd 100644
> --- a/java/jakarta/security/auth/message/AuthException.java
> +++ b/java/jakarta/security/auth/message/AuthException.java
> @@ -20,13 +20,25 @@ import java.io.Serial;
>
> import javax.security.auth.login.LoginException;
>
> +/**
> + * Exception thrown when a JASPIC authentication operation fails. This exception is used by authentication modules
> + * and contexts to signal errors during the authentication process.
> + */
> public class AuthException extends LoginException {
> @Serial
> private static final long serialVersionUID = -1156951780670243758L;
>
> + /**
> + * Constructs an AuthException with no detail message.
> + */
> public AuthException() {
> }
>
> + /**
> + * Constructs an AuthException with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public AuthException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/security/auth/message/AuthStatus.java b/java/jakarta/security/auth/message/AuthStatus.java
> index ec009c80b4..c927296493 100644
> --- a/java/jakarta/security/auth/message/AuthStatus.java
> +++ b/java/jakarta/security/auth/message/AuthStatus.java
> @@ -16,12 +16,35 @@
> */
> package jakarta.security.auth.message;
>
> +/**
> + * Represents the status returned by JASPIC authentication operations. The authentication status indicates whether
> + * authentication succeeded, failed, or requires further message exchange.
> + */
> public class AuthStatus {
>
> + /**
> + * Authentication succeeded and no further message exchange is required.
> + */
> public static final AuthStatus SUCCESS = new AuthStatus("SUCCESS");
> +
> + /**
> + * Authentication failed and no further message exchange will change the outcome.
> + */
> public static final AuthStatus FAILURE = new AuthStatus("FAILURE");
> +
> + /**
> + * Authentication succeeded and the response should be sent to the peer.
> + */
> public static final AuthStatus SEND_SUCCESS = new AuthStatus("SEND_SUCCESS");
> +
> + /**
> + * Authentication failed and the failure response should be sent to the peer.
> + */
> public static final AuthStatus SEND_FAILURE = new AuthStatus("SEND_FAILURE");
> +
> + /**
> + * Authentication is in progress and further message exchange is required.
> + */
> public static final AuthStatus SEND_CONTINUE = new AuthStatus("SEND_CONTINUE");
>
> private final String name;
> diff --git a/java/jakarta/security/auth/message/ClientAuth.java b/java/jakarta/security/auth/message/ClientAuth.java
> index 79bda35aff..a4937e06fb 100644
> --- a/java/jakarta/security/auth/message/ClientAuth.java
> +++ b/java/jakarta/security/auth/message/ClientAuth.java
> @@ -18,6 +18,10 @@ package jakarta.security.auth.message;
>
> import javax.security.auth.Subject;
>
> +/**
> + * Defines the contract for client-side authentication in JASPIC. A ClientAuth implementation authenticates outbound
> + * requests and validates inbound responses in a client-to-server communication pattern.
> + */
> public interface ClientAuth {
>
> /**
> diff --git a/java/jakarta/security/auth/message/MessageInfo.java b/java/jakarta/security/auth/message/MessageInfo.java
> index 4fd1e18f21..cb9c760132 100644
> --- a/java/jakarta/security/auth/message/MessageInfo.java
> +++ b/java/jakarta/security/auth/message/MessageInfo.java
> @@ -18,15 +18,53 @@ package jakarta.security.auth.message;
>
> import java.util.Map;
>
> +/**
> + * Represents the request and response messages associated with a
> + * message-based authentication exchange. The {@code MessageInfo} object
> + * provides access to the request and response message objects, as well
> + * as a map of additional context information. The types of the request
> + * and response message objects are protocol-specific.
> + */
> public interface MessageInfo {
>
> + /**
> + * Returns the request message object associated with this
> + * authentication exchange. The type of the returned object is
> + * protocol-specific.
> + *
> + * @return the request message object, or {@code null} if not available
> + */
> Object getRequestMessage();
>
> + /**
> + * Returns the response message object associated with this
> + * authentication exchange. The type of the returned object is
> + * protocol-specific.
> + *
> + * @return the response message object, or {@code null} if not available
> + */
> Object getResponseMessage();
>
> + /**
> + * Sets the request message object for this authentication exchange.
> + *
> + * @param request the request message object
> + */
> void setRequestMessage(Object request);
>
> + /**
> + * Sets the response message object for this authentication exchange.
> + *
> + * @param response the response message object
> + */
> void setResponseMessage(Object response);
>
> + /**
> + * Returns a map of additional context information associated with
> + * this authentication exchange. The map may contain protocol-specific
> + * attributes such as message headers.
> + *
> + * @return a {@code Map} of context information, or {@code null} if not available
> + */
> Map<String,Object> getMap();
> }
> diff --git a/java/jakarta/security/auth/message/MessagePolicy.java b/java/jakarta/security/auth/message/MessagePolicy.java
> index 3237ab42d6..7f0f3b2d12 100644
> --- a/java/jakarta/security/auth/message/MessagePolicy.java
> +++ b/java/jakarta/security/auth/message/MessagePolicy.java
> @@ -16,11 +16,28 @@
> */
> package jakarta.security.auth.message;
>
> +/**
> + * Defines the security policy requirements for a message-based
> + * authentication module. A {@code MessagePolicy} specifies the target
> + * policies that determine which messages require authentication and the
> + * level of protection required.
> + */
> public class MessagePolicy {
>
> private final TargetPolicy[] targetPolicies;
> private final boolean mandatory;
>
> + /**
> + * Creates a new {@code MessagePolicy} with the specified target
> + * policies and mandatory flag.
> + *
> + * @param targetPolicies the array of {@code TargetPolicy} objects
> + * defining the policy requirements; must not be {@code null}
> + * @param mandatory {@code true} if the policy is mandatory and
> + * authentication must succeed; {@code false} if the policy
> + * is optional
> + * @throws IllegalArgumentException if {@code targetPolicies} is {@code null}
> + */
> public MessagePolicy(TargetPolicy[] targetPolicies, boolean mandatory) {
> if (targetPolicies == null) {
> throw new IllegalArgumentException("targetPolicies is null");
> @@ -29,10 +46,23 @@ public class MessagePolicy {
> this.mandatory = mandatory;
> }
>
> + /**
> + * Indicates whether this policy is mandatory. If mandatory, the
> + * authentication module must enforce the policy and authentication
> + * will fail if the policy cannot be satisfied.
> + *
> + * @return {@code true} if the policy is mandatory, {@code false} otherwise
> + */
> public boolean isMandatory() {
> return mandatory;
> }
>
> + /**
> + * Returns the target policies associated with this message policy.
> + *
> + * @return an array of {@code TargetPolicy} objects, or {@code null}
> + * if no target policies are defined
> + */
> public TargetPolicy[] getTargetPolicies() {
> if (targetPolicies.length == 0) {
> return null;
> @@ -40,29 +70,87 @@ public class MessagePolicy {
> return targetPolicies;
> }
>
> + /**
> + * Defines the level of protection to be applied to a message.
> + * A protection policy specifies whether the sender, content,
> + * or recipient of a message must be authenticated.
> + */
> public interface ProtectionPolicy {
>
> + /**
> + * Identifier for a policy that requires authentication of the sender.
> + */
> String AUTHENTICATE_SENDER = "#authenticateSender";
> +
> + /**
> + * Identifier for a policy that requires authentication of the message content.
> + */
> String AUTHENTICATE_CONTENT = "#authenticateContent";
> +
> + /**
> + * Identifier for a policy that requires authentication of the recipient.
> + */
> String AUTHENTICATE_RECIPIENT = "#authenticateRecipient";
>
> + /**
> + * Returns the unique identifier for this protection policy.
> + *
> + * @return the string identifier for this policy
> + */
> String getID();
> }
>
> + /**
> + * Defines how to extract target information from a message for
> + * policy evaluation. A target determines which messages are
> + * subject to a particular {@code TargetPolicy}.
> + */
> public interface Target {
>
> + /**
> + * Retrieves the target value from the given message.
> + *
> + * @param messageInfo the message containing the target information
> + * @return the target value extracted from the message
> + */
> Object get(MessageInfo messageInfo);
>
> + /**
> + * Removes the target value from the given message.
> + *
> + * @param messageInfo the message from which to remove the target
> + */
> void remove(MessageInfo messageInfo);
>
> + /**
> + * Stores the target value in the given message.
> + *
> + * @param messageInfo the message in which to store the target
> + * @param data the target value to store
> + */
> void put(MessageInfo messageInfo, Object data);
> }
>
> + /**
> + * Associates a set of targets with a protection policy. A
> + * {@code TargetPolicy} defines the protection requirements for
> + * messages that match the specified targets.
> + */
> public static class TargetPolicy {
>
> private final Target[] targets;
> private final ProtectionPolicy protectionPolicy;
>
> + /**
> + * Creates a new {@code TargetPolicy} with the specified targets
> + * and protection policy.
> + *
> + * @param targets the array of {@code Target} objects, or {@code null}
> + * if not applicable
> + * @param protectionPolicy the {@code ProtectionPolicy} to apply;
> + * must not be {@code null}
> + * @throws IllegalArgumentException if {@code protectionPolicy} is {@code null}
> + */
> public TargetPolicy(Target[] targets, ProtectionPolicy protectionPolicy) {
> if (protectionPolicy == null) {
> throw new IllegalArgumentException("protectionPolicy is null");
> @@ -71,6 +159,12 @@ public class MessagePolicy {
> this.protectionPolicy = protectionPolicy;
> }
>
> + /**
> + * Returns the targets associated with this target policy.
> + *
> + * @return an array of {@code Target} objects, or {@code null}
> + * if no targets are defined
> + */
> public Target[] getTargets() {
> if (targets == null || targets.length == 0) {
> return null;
> @@ -78,6 +172,11 @@ public class MessagePolicy {
> return targets;
> }
>
> + /**
> + * Returns the protection policy associated with this target policy.
> + *
> + * @return the {@code ProtectionPolicy} for this target policy
> + */
> public ProtectionPolicy getProtectionPolicy() {
> return protectionPolicy;
> }
> diff --git a/java/jakarta/security/auth/message/ServerAuth.java b/java/jakarta/security/auth/message/ServerAuth.java
> index 8df08f055a..1508051b9d 100644
> --- a/java/jakarta/security/auth/message/ServerAuth.java
> +++ b/java/jakarta/security/auth/message/ServerAuth.java
> @@ -18,6 +18,13 @@ package jakarta.security.auth.message;
>
> import javax.security.auth.Subject;
>
> +/**
> + * Provides server-side authentication of requests and response signing.
> + * <p>
> + * This interface defines the contract for authenticating incoming requests
> + * and optionally securing outgoing responses in a server-side context.
> + * Implementations are typically obtained through a {@link jakarta.security.auth.message.config.ServerAuthContext}.
> + */
> public interface ServerAuth {
>
> /**
> diff --git a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
> index c29fca9002..11aaf37c9e 100644
> --- a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
> +++ b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
> @@ -22,8 +22,9 @@ import javax.security.auth.Subject;
> import javax.security.auth.callback.Callback;
>
> /**
> - * Callback that enables an authentication module to inform the runtime of the call principal or name of the caller
> - * principal.
> + * Callback that enables an authentication module to inform the runtime of the caller principal or name of the
> + * caller principal. The callback handler populates the given Subject with the authenticated principal, or returns
> + * the principal/name that was provided.
> */
> public class CallerPrincipalCallback implements Callback {
>
> @@ -31,26 +32,55 @@ public class CallerPrincipalCallback implements Callback {
> private final Principal principal;
> private final String name;
>
> + /**
> + * Constructs a callback with a Subject and a Principal. The callback handler will add the principal to the
> + * subject.
> + *
> + * @param subject the subject to which the principal will be added
> + * @param principal the principal representing the caller
> + */
> public CallerPrincipalCallback(Subject subject, Principal principal) {
> this.subject = subject;
> this.principal = principal;
> this.name = null;
> }
>
> + /**
> + * Constructs a callback with a Subject and a caller name. The callback handler will create a principal from
> + * the name and add it to the subject.
> + *
> + * @param subject the subject to which the principal will be added
> + * @param name the name of the caller
> + */
> public CallerPrincipalCallback(Subject subject, String name) {
> this.subject = subject;
> this.principal = null;
> this.name = name;
> }
>
> + /**
> + * Returns the Subject associated with this callback.
> + *
> + * @return the Subject
> + */
> public Subject getSubject() {
> return subject;
> }
>
> + /**
> + * Returns the Principal associated with this callback, or {@code null} if a name was provided instead.
> + *
> + * @return the Principal, or {@code null}
> + */
> public Principal getPrincipal() {
> return principal;
> }
>
> + /**
> + * Returns the name associated with this callback, or {@code null} if a Principal was provided instead.
> + *
> + * @return the name, or {@code null}
> + */
> public String getName() {
> return name;
> }
> diff --git a/java/jakarta/security/auth/message/callback/CertStoreCallback.java b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
> index d8aef96cb2..f30a9dbf95 100644
> --- a/java/jakarta/security/auth/message/callback/CertStoreCallback.java
> +++ b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
> @@ -21,19 +21,33 @@ import java.security.cert.CertStore;
> import javax.security.auth.callback.Callback;
>
> /**
> - * Callback that enables a runtime to inform authentication modules of the CertStore to use.
> + * Callback that enables a runtime to inform authentication modules of the {@link CertStore} to use for certificate
> + * validation. The runtime populates the CertStore, and the authentication module retrieves it.
> */
> public class CertStoreCallback implements Callback {
>
> private CertStore certStore;
>
> + /**
> + * Constructs an empty CertStoreCallback. The runtime will populate the CertStore via {@link #setCertStore}.
> + */
> public CertStoreCallback() {
> }
>
> + /**
> + * Sets the CertStore to be used for certificate validation.
> + *
> + * @param certStore the CertStore
> + */
> public void setCertStore(CertStore certStore) {
> this.certStore = certStore;
> }
>
> + /**
> + * Returns the CertStore set by the runtime.
> + *
> + * @return the CertStore, or {@code null} if not yet set
> + */
> public CertStore getCertStore() {
> return certStore;
> }
> diff --git a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
> index f5b2e55ffe..4f053e22f0 100644
> --- a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
> +++ b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
> @@ -21,21 +21,40 @@ import javax.security.auth.callback.Callback;
>
> /**
> * Callback that enables an authentication module to inform the runtime of the groups a user is in.
> + * The callback handler populates the given Subject with the group principals, or returns the
> + * group names that were provided.
> */
> public class GroupPrincipalCallback implements Callback {
>
> private final Subject subject;
> private final String[] groups;
>
> + /**
> + * Constructs a callback with a Subject and an array of group names. The callback handler
> + * will create principals for the group names and add them to the subject.
> + *
> + * @param subject the subject to which the group principals will be added
> + * @param groups the group names associated with the caller
> + */
> public GroupPrincipalCallback(Subject subject, String[] groups) {
> this.subject = subject;
> this.groups = groups;
> }
>
> + /**
> + * Returns the Subject associated with this callback.
> + *
> + * @return the Subject
> + */
> public Subject getSubject() {
> return subject;
> }
>
> + /**
> + * Returns the group names associated with this callback.
> + *
> + * @return the group names
> + */
> public String[] getGroups() {
> return groups;
> }
> diff --git a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
> index ae9f6bdecc..d552255736 100644
> --- a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
> +++ b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
> @@ -22,8 +22,10 @@ import javax.security.auth.Subject;
> import javax.security.auth.callback.Callback;
>
> /**
> - * Callback that enables an authentication module to supply a username and password (to a runtime?) and determine if the
> - * result of validation.
> + * A callback that enables an authentication module to supply a username
> + * and password to the runtime and obtain the result of password validation.
> + * The runtime validates the credentials and updates the {@code Subject}
> + * if authentication succeeds.
> */
> public class PasswordValidationCallback implements Callback {
>
> @@ -32,33 +34,76 @@ public class PasswordValidationCallback implements Callback {
> private char[] password;
> private boolean result;
>
> + /**
> + * Creates a new {@code PasswordValidationCallback} with the specified
> + * subject, username, and password.
> + *
> + * @param subject the {@code Subject} to be populated upon successful
> + * authentication
> + * @param username the username to validate
> + * @param password the password to validate
> + */
> public PasswordValidationCallback(Subject subject, String username, char[] password) {
> this.subject = subject;
> this.username = username;
> this.password = password;
> }
>
> + /**
> + * Returns the {@code Subject} associated with this callback. The
> + * runtime populates this subject with authentication information
> + * upon successful validation.
> + *
> + * @return the {@code Subject} for this callback
> + */
> public Subject getSubject() {
> return subject;
> }
>
> + /**
> + * Returns the username to be validated.
> + *
> + * @return the username
> + */
> public String getUsername() {
> return username;
> }
>
> + /**
> + * Returns the password to be validated.
> + *
> + * @return the password character array
> + */
> public char[] getPassword() {
> return password;
> }
>
> + /**
> + * Clears the password from memory for security purposes. After
> + * calling this method, {@link #getPassword()} will return an empty
> + * character array.
> + */
> public void clearPassword() {
> Arrays.fill(password, (char) 0);
> password = new char[0];
> }
>
> + /**
> + * Sets the result of the password validation performed by the runtime.
> + *
> + * @param result {@code true} if the password validation succeeded,
> + * {@code false} otherwise
> + */
> public void setResult(boolean result) {
> this.result = result;
> }
>
> + /**
> + * Returns the result of the password validation.
> + *
> + * @return {@code true} if the password was validated successfully,
> + * {@code false} otherwise
> + */
> public boolean getResult() {
> return result;
> }
> diff --git a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
> index 853ca02600..c3aab997d6 100644
> --- a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
> +++ b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
> @@ -24,9 +24,11 @@ import javax.security.auth.callback.Callback;
> import javax.security.auth.x500.X500Principal;
>
> /**
> - * Callback that enables an authentication module to request a certificate chain and private key from the runtime. The
> - * information specifying the chain and key may be an alias, a digest, a subject key, or an issuer ID. Other request
> - * types may be supported.
> + * A callback that enables an authentication module to request a
> + * certificate chain and private key from the runtime. The request
> + * identifies the desired key material using one of several {@link Request}
> + * subtypes, such as keystore alias, certificate digest, subject key
> + * identifier, or issuer and serial number.
> */
> public class PrivateKeyCallback implements Callback {
>
> @@ -34,87 +36,192 @@ public class PrivateKeyCallback implements Callback {
> private Certificate[] chain;
> private PrivateKey key;
>
> + /**
> + * Creates a new {@code PrivateKeyCallback} with the specified request.
> + *
> + * @param request the {@code Request} object identifying the desired
> + * certificate chain and private key
> + */
> public PrivateKeyCallback(Request request) {
> this.request = request;
> }
>
> + /**
> + * Returns the request associated with this callback.
> + *
> + * @return the {@code Request} object
> + */
> public Request getRequest() {
> return request;
> }
>
> + /**
> + * Sets the private key and certificate chain resolved by the runtime
> + * in response to the request.
> + *
> + * @param key the resolved {@code PrivateKey}
> + * @param chain the corresponding certificate chain
> + */
> public void setKey(PrivateKey key, Certificate[] chain) {
> this.key = key;
> this.chain = chain;
> }
>
> + /**
> + * Returns the private key resolved by the runtime.
> + *
> + * @return the {@code PrivateKey}, or {@code null} if not yet resolved
> + */
> public PrivateKey getKey() {
> return key;
> }
>
> + /**
> + * Returns the certificate chain resolved by the runtime.
> + *
> + * @return the certificate chain, or {@code null} if not yet resolved
> + */
> public Certificate[] getChain() {
> return chain;
> }
>
> + /**
> + * Base interface for private key requests. Implementations specify
> + * the criteria by which the runtime should locate the desired
> + * certificate chain and private key.
> + */
> public interface Request {
> }
>
> + /**
> + * A request to retrieve a certificate chain and private key by
> + * keystore alias.
> + */
> public static class AliasRequest implements Request {
>
> private final String alias;
>
> + /**
> + * Creates a new {@code AliasRequest} with the specified keystore alias.
> + *
> + * @param alias the keystore alias identifying the desired key entry
> + */
> public AliasRequest(String alias) {
> this.alias = alias;
> }
>
> + /**
> + * Returns the keystore alias for this request.
> + *
> + * @return the keystore alias
> + */
> public String getAlias() {
> return alias;
> }
> }
>
> + /**
> + * A request to retrieve a certificate chain and private key by
> + * certificate digest value.
> + */
> public static class DigestRequest implements Request {
> private final byte[] digest;
> private final String algorithm;
>
> + /**
> + * Creates a new {@code DigestRequest} with the specified digest
> + * value and digest algorithm.
> + *
> + * @param digest the digest value of the desired certificate
> + * @param algorithm the digest algorithm used to produce the digest
> + */
> public DigestRequest(byte[] digest, String algorithm) {
> this.digest = digest;
> this.algorithm = algorithm;
> }
>
> + /**
> + * Returns the digest value for this request.
> + *
> + * @return the digest byte array
> + */
> public byte[] getDigest() {
> return digest;
> }
>
> + /**
> + * Returns the digest algorithm used for this request.
> + *
> + * @return the algorithm name
> + */
> public String getAlgorithm() {
> return algorithm;
> }
> }
>
> + /**
> + * A request to retrieve a certificate chain and private key by
> + * the Subject Key Identifier extension value.
> + */
> public static class SubjectKeyIDRequest implements Request {
>
> private final byte[] subjectKeyID;
>
> + /**
> + * Creates a new {@code SubjectKeyIDRequest} with the specified
> + * subject key identifier.
> + *
> + * @param subjectKeyID the Subject Key Identifier extension value
> + * from the desired certificate
> + */
> public SubjectKeyIDRequest(byte[] subjectKeyID) {
> this.subjectKeyID = subjectKeyID;
> }
>
> + /**
> + * Returns the subject key identifier for this request.
> + *
> + * @return the Subject Key Identifier byte array
> + */
> public byte[] getSubjectKeyID() {
> return subjectKeyID;
> }
> }
>
> + /**
> + * A request to retrieve a certificate chain and private key by
> + * the issuer distinguished name and certificate serial number.
> + */
> public static class IssuerSerialNumRequest implements Request {
> private final X500Principal issuer;
> private final BigInteger serialNum;
>
> + /**
> + * Creates a new {@code IssuerSerialNumRequest} with the specified
> + * issuer and serial number.
> + *
> + * @param issuer the issuer distinguished name of the desired certificate
> + * @param serialNum the serial number of the desired certificate
> + */
> public IssuerSerialNumRequest(X500Principal issuer, BigInteger serialNum) {
> this.issuer = issuer;
> this.serialNum = serialNum;
> }
>
> + /**
> + * Returns the issuer distinguished name for this request.
> + *
> + * @return the {@code X500Principal} representing the issuer
> + */
> public X500Principal getIssuer() {
> return issuer;
> }
>
> + /**
> + * Returns the certificate serial number for this request.
> + *
> + * @return the serial number as a {@code BigInteger}
> + */
> public BigInteger getSerialNum() {
> return serialNum;
> }
> diff --git a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
> index b3a02ad938..7cf47cdec8 100644
> --- a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
> +++ b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
> @@ -28,33 +28,70 @@ public class SecretKeyCallback implements Callback {
> private final Request request;
> private SecretKey key;
>
> + /**
> + * Constructs a SecretKeyCallback with the specified request.
> + *
> + * @param request The request describing the secret key to obtain
> + */
> public SecretKeyCallback(Request request) {
> this.request = request;
> }
>
> + /**
> + * Returns the request associated with this callback.
> + *
> + * @return The request describing the secret key to obtain
> + */
> public Request getRequest() {
> return request;
> }
>
> + /**
> + * Sets the secret key obtained by the runtime.
> + *
> + * @param key The secret key
> + */
> public void setKey(SecretKey key) {
> this.key = key;
> }
>
> + /**
> + * Returns the secret key.
> + *
> + * @return The secret key, or {@code null} if not set
> + */
> public SecretKey getKey() {
> return key;
> }
>
> + /**
> + * Represents a request for a secret key.
> + * Implementations specify the criteria for locating the desired key.
> + */
> public interface Request {
> }
>
> + /**
> + * A request for a secret key identified by its alias.
> + */
> public static class AliasRequest implements Request {
>
> private final String alias;
>
> + /**
> + * Constructs an AliasRequest with the specified alias.
> + *
> + * @param alias The alias of the secret key to obtain
> + */
> public AliasRequest(String alias) {
> this.alias = alias;
> }
>
> + /**
> + * Returns the alias of the requested secret key.
> + *
> + * @return The alias string
> + */
> public String getAlias() {
> return alias;
> }
> diff --git a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
> index 9bafa9a26b..a6a367ba19 100644
> --- a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
> +++ b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
> @@ -27,10 +27,26 @@ public class TrustStoreCallback implements Callback {
>
> private KeyStore trustStore;
>
> + /**
> + * Constructs a new TrustStoreCallback.
> + */
> + public TrustStoreCallback() {
> + }
> +
> + /**
> + * Sets the trust store to be used for certificate validation.
> + *
> + * @param trustStore The trust store containing trusted certificates
> + */
> public void setTrustStore(KeyStore trustStore) {
> this.trustStore = trustStore;
> }
>
> + /**
> + * Returns the trust store.
> + *
> + * @return The trust store, or {@code null} if not set
> + */
> public KeyStore getTrustStore() {
> return trustStore;
> }
> diff --git a/java/jakarta/security/auth/message/config/AuthConfig.java b/java/jakarta/security/auth/message/config/AuthConfig.java
> index 099cccee8d..7e3e5e0572 100644
> --- a/java/jakarta/security/auth/message/config/AuthConfig.java
> +++ b/java/jakarta/security/auth/message/config/AuthConfig.java
> @@ -18,15 +18,46 @@ package jakarta.security.auth.message.config;
>
> import jakarta.security.auth.message.MessageInfo;
>
> +/**
> + * Provides configuration information for a JASPIC authentication mechanism. An AuthConfig defines the message layer,
> + * application context, and authentication context ID for a given message, and indicates whether the mechanism is
> + * protected.
> + */
> public interface AuthConfig {
>
> + /**
> + * Returns the message layer for which this configuration applies.
> + *
> + * @return the message layer
> + */
> String getMessageLayer();
>
> + /**
> + * Returns the application context for which this configuration applies.
> + *
> + * @return the application context
> + */
> String getAppContext();
>
> + /**
> + * Determines the authentication context ID for the given message.
> + *
> + * @param messageInfo the message information used to determine the context ID
> + *
> + * @return the authentication context ID, or {@code null} if no context applies
> + */
> String getAuthContextID(MessageInfo messageInfo);
>
> + /**
> + * Refreshes the configuration, reloading any changed settings.
> + */
> void refresh();
>
> + /**
> + * Indicates whether the authentication mechanism is protected, meaning that the configuration data is stored
> + * securely.
> + *
> + * @return {@code true} if the mechanism is protected, {@code false} otherwise
> + */
> boolean isProtected();
> }
> diff --git a/java/jakarta/security/auth/message/config/AuthConfigFactory.java b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
> index e8f4938ad6..7d56046cf3 100644
> --- a/java/jakarta/security/auth/message/config/AuthConfigFactory.java
> +++ b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
> @@ -21,8 +21,17 @@ import java.util.Map;
>
> import jakarta.security.auth.message.module.ServerAuthModule;
>
> +/**
> + * Factory for obtaining and managing {@link AuthConfigProvider} instances. The AuthConfigFactory is responsible for
> + * discovering, registering, and providing configuration providers for JASPIC authentication modules. Use
> + * {@link #getFactory()} to obtain the singleton instance.
> + */
> public abstract class AuthConfigFactory {
>
> + /**
> + * The name of the {@link java.security.Security} property used to specify the AuthConfigFactory implementation
> + * class.
> + */
> public static final String DEFAULT_FACTORY_SECURITY_PROPERTY = "authconfigprovider.factory";
>
> private static final String DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL =
> @@ -30,9 +39,19 @@ public abstract class AuthConfigFactory {
>
> private static volatile AuthConfigFactory factory;
>
> + /**
> + * Protected constructor for subclasses.
> + */
> public AuthConfigFactory() {
> }
>
> + /**
> + * Returns the singleton AuthConfigFactory instance. If no instance has been set via {@link #setFactory}, the
> + * factory class is discovered from the {@link java.security.Security} property
> + * {@value #DEFAULT_FACTORY_SECURITY_PROPERTY}, or falls back to a default implementation.
> + *
> + * @return the AuthConfigFactory instance
> + */
> public static AuthConfigFactory getFactory() {
> if (factory != null) {
> return factory;
> @@ -61,27 +80,97 @@ public abstract class AuthConfigFactory {
> return factory;
> }
>
> + /**
> + * Programmatically sets the AuthConfigFactory instance. This method is typically used by containers to provide
> + * their own implementation.
> + *
> + * @param factory the AuthConfigFactory instance to set
> + */
> public static synchronized void setFactory(AuthConfigFactory factory) {
> AuthConfigFactory.factory = factory;
> }
>
> + /**
> + * Returns the {@link AuthConfigProvider} for the specified message layer and application context.
> + *
> + * @param layer the message layer
> + * @param appContext the application context
> + * @param listener the registration listener to attach
> + *
> + * @return the AuthConfigProvider, or {@code null} if none is available
> + */
> public abstract AuthConfigProvider getConfigProvider(String layer, String appContext,
> RegistrationListener listener);
>
> + /**
> + * Registers an AuthConfigProvider by class name with the given properties.
> + *
> + * @param className the fully qualified class name of the AuthConfigProvider
> + * @param properties the configuration properties
> + * @param layer the message layer
> + * @param appContext the application context
> + * @param description a description of the registration
> + *
> + * @return a unique registration ID
> + */
> public abstract String registerConfigProvider(String className, Map<String,String> properties, String layer,
> String appContext, String description);
>
> + /**
> + * Registers an AuthConfigProvider instance.
> + *
> + * @param provider the AuthConfigProvider to register
> + * @param layer the message layer
> + * @param appContext the application context
> + * @param description a description of the registration
> + *
> + * @return a unique registration ID
> + */
> public abstract String registerConfigProvider(AuthConfigProvider provider, String layer, String appContext,
> String description);
>
> + /**
> + * Removes a registration by its ID.
> + *
> + * @param registrationID the registration ID to remove
> + *
> + * @return {@code true} if the registration was removed, {@code false} if it did not exist
> + */
> public abstract boolean removeRegistration(String registrationID);
>
> + /**
> + * Detaches a listener from all registrations matching the given layer and application context, returning the
> + * affected registration IDs.
> + *
> + * @param listener the listener to detach
> + * @param layer the message layer
> + * @param appContext the application context
> + *
> + * @return an array of registration IDs from which the listener was detached
> + */
> public abstract String[] detachListener(RegistrationListener listener, String layer, String appContext);
>
> + /**
> + * Returns the registration IDs associated with the given AuthConfigProvider.
> + *
> + * @param provider the AuthConfigProvider
> + *
> + * @return an array of registration IDs
> + */
> public abstract String[] getRegistrationIDs(AuthConfigProvider provider);
>
> + /**
> + * Returns the {@link RegistrationContext} for the given registration ID.
> + *
> + * @param registrationID the registration ID
> + *
> + * @return the RegistrationContext, or {@code null} if the ID is not found
> + */
> public abstract RegistrationContext getRegistrationContext(String registrationID);
>
> + /**
> + * Refreshes all registered AuthConfigProviders, causing them to reload their configuration.
> + */
> public abstract void refresh();
>
> /**
> @@ -118,14 +207,37 @@ public abstract class AuthConfigFactory {
> return DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL;
> }
>
> + /**
> + * Provides information about a registered {@link AuthConfigProvider}.
> + */
> public interface RegistrationContext {
>
> + /**
> + * Returns the message layer for this registration.
> + *
> + * @return the message layer
> + */
> String getMessageLayer();
>
> + /**
> + * Returns the application context for this registration.
> + *
> + * @return the application context
> + */
> String getAppContext();
>
> + /**
> + * Returns the description of this registration.
> + *
> + * @return the description
> + */
> String getDescription();
>
> + /**
> + * Indicates whether this registration persists beyond the current container lifecycle.
> + *
> + * @return {@code true} if the registration is persistent, {@code false} otherwise
> + */
> boolean isPersistent();
> }
> }
> diff --git a/java/jakarta/security/auth/message/config/AuthConfigProvider.java b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
> index 66410a7e13..9f42dafd06 100644
> --- a/java/jakarta/security/auth/message/config/AuthConfigProvider.java
> +++ b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
> @@ -20,11 +20,41 @@ import javax.security.auth.callback.CallbackHandler;
>
> import jakarta.security.auth.message.AuthException;
>
> +/**
> + * Provides {@link ClientAuthConfig} and {@link ServerAuthConfig} instances to JASPIC authentication modules. An
> + * AuthConfigProvider is responsible for loading authentication configuration from a source (e.g., a configuration
> + * file, database, or service) and making it available to the authentication modules.
> + */
> public interface AuthConfigProvider {
>
> + /**
> + * Returns the client-side authentication configuration for the specified layer and application context.
> + *
> + * @param layer the message layer
> + * @param appContext the application context
> + * @param handler the callback handler for obtaining sensitive configuration data
> + *
> + * @return the ClientAuthConfig, or {@code null} if no configuration is available
> + *
> + * @throws AuthException if an error occurs while retrieving the configuration
> + */
> ClientAuthConfig getClientAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
>
> + /**
> + * Returns the server-side authentication configuration for the specified layer and application context.
> + *
> + * @param layer the message layer
> + * @param appContext the application context
> + * @param handler the callback handler for obtaining sensitive configuration data
> + *
> + * @return the ServerAuthConfig, or {@code null} if no configuration is available
> + *
> + * @throws AuthException if an error occurs while retrieving the configuration
> + */
> ServerAuthConfig getServerAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
>
> + /**
> + * Refreshes the configuration, reloading any changed settings from the underlying source.
> + */
> void refresh();
> }
> diff --git a/java/jakarta/security/auth/message/config/ClientAuthConfig.java b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
> index f332f0fea6..8c588bda46 100644
> --- a/java/jakarta/security/auth/message/config/ClientAuthConfig.java
> +++ b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
> @@ -22,8 +22,23 @@ import javax.security.auth.Subject;
>
> import jakarta.security.auth.message.AuthException;
>
> +/**
> + * Client-side authentication configuration obtained from an {@link AuthConfigProvider}. A ClientAuthConfig provides
> + * the configuration needed to create a {@link ClientAuthContext} for authenticating outbound requests.
> + */
> public interface ClientAuthConfig extends AuthConfig {
>
> + /**
> + * Creates a {@link ClientAuthContext} for the specified authentication context ID.
> + *
> + * @param authContextID the authentication context ID
> + * @param clientSubject the subject representing the client, to be populated upon successful authentication
> + * @param properties additional configuration properties
> + *
> + * @return the ClientAuthContext, or {@code null} if the authContextID is not recognized
> + *
> + * @throws AuthException if an error occurs while creating the context
> + */
> ClientAuthContext getAuthContext(String authContextID, Subject clientSubject, Map<String,Object> properties)
> throws AuthException;
> }
> diff --git a/java/jakarta/security/auth/message/config/ClientAuthContext.java b/java/jakarta/security/auth/message/config/ClientAuthContext.java
> index 53280c7822..1c7f95c53b 100644
> --- a/java/jakarta/security/auth/message/config/ClientAuthContext.java
> +++ b/java/jakarta/security/auth/message/config/ClientAuthContext.java
> @@ -18,5 +18,10 @@ package jakarta.security.auth.message.config;
>
> import jakarta.security.auth.message.ClientAuth;
>
> +/**
> + * Runtime context for client-side JASPIC authentication. A ClientAuthContext is created by a
> + * {@link ClientAuthConfig} and performs the actual authentication of outbound requests and validation of inbound
> + * responses.
> + */
> public interface ClientAuthContext extends ClientAuth {
> }
> diff --git a/java/jakarta/security/auth/message/config/RegistrationListener.java b/java/jakarta/security/auth/message/config/RegistrationListener.java
> index 05bec1c163..9c3053660b 100644
> --- a/java/jakarta/security/auth/message/config/RegistrationListener.java
> +++ b/java/jakarta/security/auth/message/config/RegistrationListener.java
> @@ -16,7 +16,16 @@
> */
> package jakarta.security.auth.message.config;
>
> +/**
> + * Listener interface for JASPIC registration events.
> + */
> public interface RegistrationListener {
>
> + /**
> + * Notifies the listener of a registration event.
> + *
> + * @param layer the authentication layer
> + * @param appContext the application context
> + */
> void notify(String layer, String appContext);
> }
> diff --git a/java/jakarta/security/auth/message/config/ServerAuthConfig.java b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
> index a8bc9c728c..f970ea5466 100644
> --- a/java/jakarta/security/auth/message/config/ServerAuthConfig.java
> +++ b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
> @@ -22,8 +22,20 @@ import javax.security.auth.Subject;
>
> import jakarta.security.auth.message.AuthException;
>
> +/**
> + * Server-side authentication configuration obtained from an {@link AuthConfigProvider}.
> + */
> public interface ServerAuthConfig extends AuthConfig {
>
> + /**
> + * Returns the {@link ServerAuthContext} for the given authentication context ID.
> + *
> + * @param authContextID the authentication context identifier
> + * @param serviceSubject the service subject
> + * @param properties the configuration properties
> + * @return the server authentication context
> + * @throws AuthException if an error occurs during authentication context creation
> + */
> ServerAuthContext getAuthContext(String authContextID, Subject serviceSubject, Map<String,Object> properties)
> throws AuthException;
> }
> diff --git a/java/jakarta/security/auth/message/config/ServerAuthContext.java b/java/jakarta/security/auth/message/config/ServerAuthContext.java
> index bbff396988..4c668f7ba5 100644
> --- a/java/jakarta/security/auth/message/config/ServerAuthContext.java
> +++ b/java/jakarta/security/auth/message/config/ServerAuthContext.java
> @@ -18,5 +18,12 @@ package jakarta.security.auth.message.config;
>
> import jakarta.security.auth.message.ServerAuth;
>
> +/**
> + * Provides server-side authentication of requests and response signing.
> + * <p>
> + * This interface extends {@link ServerAuth} and is obtained from a
> + * {@link ServerAuthConfig}. It is used by the container to authenticate
> + * incoming requests and secure outgoing responses.
> + */
> public interface ServerAuthContext extends ServerAuth {
> }
> diff --git a/java/jakarta/security/auth/message/module/ClientAuthModule.java b/java/jakarta/security/auth/message/module/ClientAuthModule.java
> index b0569a462c..ef0d8be7a4 100644
> --- a/java/jakarta/security/auth/message/module/ClientAuthModule.java
> +++ b/java/jakarta/security/auth/message/module/ClientAuthModule.java
> @@ -24,10 +24,31 @@ import jakarta.security.auth.message.AuthException;
> import jakarta.security.auth.message.ClientAuth;
> import jakarta.security.auth.message.MessagePolicy;
>
> +/**
> + * A pluggable client-side authentication module in JASPIC. A ClientAuthModule implements the authentication logic
> + * for client-side operations and is initialized with message policies, a callback handler, and configuration
> + * options.
> + */
> public interface ClientAuthModule extends ClientAuth {
>
> + /**
> + * Initializes the authentication module with the given policies, callback handler, and options. This method is
> + * called once when the module is created.
> + *
> + * @param requestPolicy the message policy for requests
> + * @param responsePolicy the message policy for responses
> + * @param handler the callback handler for obtaining sensitive data
> + * @param options configuration options for the module
> + *
> + * @throws AuthException if initialization fails
> + */
> void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
> Map<String,Object> options) throws AuthException;
>
> + /**
> + * Returns the array of MessageInfo implementation classes supported by this module.
> + *
> + * @return an array of supported MessageInfo classes
> + */
> Class<?>[] getSupportedMessageTypes();
> }
> diff --git a/java/jakarta/security/auth/message/module/ServerAuthModule.java b/java/jakarta/security/auth/message/module/ServerAuthModule.java
> index 3518bea61d..66e7297fbb 100644
> --- a/java/jakarta/security/auth/message/module/ServerAuthModule.java
> +++ b/java/jakarta/security/auth/message/module/ServerAuthModule.java
> @@ -24,10 +24,35 @@ import jakarta.security.auth.message.AuthException;
> import jakarta.security.auth.message.MessagePolicy;
> import jakarta.security.auth.message.ServerAuth;
>
> +/**
> + * Provides server-side authentication of requests and response signing.
> + * <p>
> + * This interface extends {@link ServerAuth} and is implemented by authentication
> + * module providers. It is initialized by the container and provides the actual
> + * authentication logic for server-side message authentication.
> + */
> public interface ServerAuthModule extends ServerAuth {
>
> + /**
> + * Initialize the authentication module.
> + * <p>
> + * This method is called by the container to initialize the module with the
> + * request and response policies, a callback handler, and a set of options.
> + *
> + * @param requestPolicy The policy for the request message
> + * @param responsePolicy The policy for the response message
> + * @param handler The callback handler used to obtain credentials
> + * @param options The options provided to the module
> + *
> + * @throws AuthException If an error occurs during initialization
> + */
> void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
> Map<String,Object> options) throws AuthException;
>
> + /**
> + * Returns the array of message types supported by the module.
> + *
> + * @return The array of supported message type classes
> + */
> Class<?>[] getSupportedMessageTypes();
> }
> diff --git a/java/jakarta/servlet/AsyncContext.java b/java/jakarta/servlet/AsyncContext.java
> index 7b952e6394..5ba0e7eb53 100644
> --- a/java/jakarta/servlet/AsyncContext.java
> +++ b/java/jakarta/servlet/AsyncContext.java
> @@ -54,21 +54,32 @@ public interface AsyncContext {
> String ASYNC_QUERY_STRING = "jakarta.servlet.async.query_string";
>
> /**
> - * @return a reference to the ServletRequest object
> + * Returns the {@link ServletRequest} associated with this asynchronous operation.
> + *
> + * @return the ServletRequest object
> */
> ServletRequest getRequest();
>
> /**
> - * @return a reference to the ServletResponse object
> + * Returns the {@link ServletResponse} associated with this asynchronous operation.
> + *
> + * @return the ServletResponse object
> */
> ServletResponse getResponse();
>
> /**
> - * @return true if the Request and Response are the original ones
> + * Determines whether the request and response objects are the original ones passed to
> + * {@link jakarta.servlet.http.HttpServletRequest#startAsync()}, or if they are new objects created by the
> + * container.
> + *
> + * @return {@code true} if the request and response are the original objects, {@code false} otherwise
> */
> boolean hasOriginalRequestAndResponse();
>
> /**
> + * Dispatches the request to the resource at the original request URI, as specified in the original request. After
> + * the dispatch, the async request processing is complete and the response is committed.
> + *
> * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
> * is in asynchronous mode after
> * {@link jakarta.servlet.http.HttpServletRequest#startAsync()} or
> @@ -79,8 +90,12 @@ public interface AsyncContext {
> void dispatch();
>
> /**
> - * @param path The path to which the request/response should be dispatched relative to the {@link ServletContext}
> - * from which this async request was started.
> + * Dispatches the request to the resource at the specified path relative to the {@link ServletContext} from which
> + * this async request was started. After the dispatch, the async request processing is complete and the response
> + * is committed.
> + *
> + * @param path the path to which the request/response should be dispatched relative to the {@link ServletContext}
> + * from which this async request was started
> *
> * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
> * is in asynchronous mode after
> @@ -92,9 +107,12 @@ public interface AsyncContext {
> void dispatch(String path);
>
> /**
> - * @param path The path to which the request/response should be dispatched relative to the specified
> - * {@link ServletContext}.
> - * @param context The {@link ServletContext} to which the request/response should be dispatched.
> + * Dispatches the request to the resource at the specified path relative to the given {@link ServletContext}.
> + * After the dispatch, the async request processing is complete and the response is committed.
> + *
> + * @param path the path to which the request/response should be dispatched relative to the specified
> + * {@link ServletContext}
> + * @param context the {@link ServletContext} to which the request/response should be dispatched
> *
> * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
> * is in asynchronous mode after
> diff --git a/java/jakarta/servlet/GenericFilter.java b/java/jakarta/servlet/GenericFilter.java
> index 67b7962d79..ef6b8fb901 100644
> --- a/java/jakarta/servlet/GenericFilter.java
> +++ b/java/jakarta/servlet/GenericFilter.java
> @@ -34,11 +34,18 @@ public abstract class GenericFilter implements Filter, FilterConfig, Serializabl
> @Serial
> private static final long serialVersionUID = 1L;
>
> - /**
> - * The filter configuration.
> - */
> + /**
> + * The filter configuration.
> + */
> private volatile FilterConfig filterConfig;
>
> + /**
> + * Constructs a new GenericFilter.
> + */
> + public GenericFilter() {
> + // NO-OP
> + }
> +
>
> @Override
> public String getInitParameter(String name) {
> diff --git a/java/jakarta/servlet/HttpConstraintElement.java b/java/jakarta/servlet/HttpConstraintElement.java
> index 90e310295c..51b3c41a50 100644
> --- a/java/jakarta/servlet/HttpConstraintElement.java
> +++ b/java/jakarta/servlet/HttpConstraintElement.java
> @@ -89,27 +89,27 @@ public class HttpConstraintElement {
> }
>
> /**
> - * TODO
> + * Returns the empty role semantic for this constraint.
> *
> - * @return TODO
> + * @return The empty role semantic for this constraint
> */
> public EmptyRoleSemantic getEmptyRoleSemantic() {
> return emptyRoleSemantic;
> }
>
> /**
> - * TODO
> + * Returns the transport guarantee for this constraint.
> *
> - * @return TODO
> + * @return The transport guarantee for this constraint
> */
> public TransportGuarantee getTransportGuarantee() {
> return transportGuarantee;
> }
>
> /**
> - * TODO
> + * Returns the roles allowed for this constraint.
> *
> - * @return TODO
> + * @return The roles allowed for this constraint
> */
> public String[] getRolesAllowed() {
> return rolesAllowed;
> diff --git a/java/jakarta/servlet/ServletContext.java b/java/jakarta/servlet/ServletContext.java
> index 15eba5a3a5..adf8ececdf 100644
> --- a/java/jakarta/servlet/ServletContext.java
> +++ b/java/jakarta/servlet/ServletContext.java
> @@ -551,7 +551,7 @@ public interface ServletContext {
> *
> * @since Servlet 3.0
> */
> - Map<String,? extends ServletRegistration> getServletRegistrations();
> + Map<String, ? extends ServletRegistration> getServletRegistrations();
>
> /**
> * Add filter to context.
> @@ -644,11 +644,11 @@ public interface ServletContext {
> <T extends Filter> T createFilter(Class<T> c) throws ServletException;
>
> /**
> - * TODO SERVLET3 - Add comments
> + * Returns the {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists.
> *
> - * @param filterName TODO
> + * @param filterName The name of the filter for which to return the registration
> *
> - * @return TODO
> + * @return The {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists
> *
> * @throws UnsupportedOperationException If called from a
> * {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> @@ -663,7 +663,10 @@ public interface ServletContext {
> FilterRegistration getFilterRegistration(String filterName);
>
> /**
> - * @return TODO
> + * Returns an immutable Map of all the filter registrations for this web application, where the key is the filter
> + * name and the value is the {@link FilterRegistration} object.
> + *
> + * @return An immutable Map of all the filter registrations for this web application
> *
> * @throws UnsupportedOperationException If called from a
> * {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> @@ -673,12 +676,15 @@ public interface ServletContext {
> * {@link ServletContextListener} defined in a TLD would not be able to
> * use this method.
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @since Servlet 3.0
> */
> - Map<String,? extends FilterRegistration> getFilterRegistrations();
> + Map<String, ? extends FilterRegistration> getFilterRegistrations();
>
> /**
> - * @return TODO
> + * Returns the {@link SessionCookieConfig} object for this web application, which can be used to configure the
> + * session tracking cookie.
> + *
> + * @return The {@link SessionCookieConfig} object for this web application
> *
> * @throws UnsupportedOperationException If called from a
> * {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> @@ -688,7 +694,7 @@ public interface ServletContext {
> * {@link ServletContextListener} defined in a TLD would not be able to
> * use this method.
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @since Servlet 3.0
> */
> SessionCookieConfig getSessionCookieConfig();
>
> @@ -735,10 +741,20 @@ public interface ServletContext {
> Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
>
> /**
> - * TODO SERVLET3 - Add comments
> + * Adds a listener to this web application. The listener instance will be created by the container using the
> + * no-argument constructor of the given class.
> *
> - * @param className TODO
> + * @param className The fully qualified class name of the listener to add
> *
> + * @throws ClassCastException If the class name does not implement {@link EventListener} or a
> + * subinterface recognized by the servlet container, or if a non-standard
> + * listener type is not packaged in a JAR file with a
> + * <code>listener</code> element in the <code>META-INF/services</code>
> + * directory
> + * @throws IllegalArgumentException If the lifecycle of a listener prohibits addition at runtime, or if the
> + * class has a {@link jakarta.servlet.annotation.WebListener} annotation
> + * that conflicts with the programmatic addition
> + * @throws IllegalStateException If the context has already been initialised
> * @throws UnsupportedOperationException If called from a
> * {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> * method of a {@link ServletContextListener} that was not defined in a
> @@ -752,11 +768,20 @@ public interface ServletContext {
> void addListener(String className);
>
> /**
> - * TODO SERVLET3 - Add comments
> + * Adds the given listener instance to this web application.
> *
> - * @param <T> TODO
> - * @param t TODO
> + * @param <T> The type of listener being added
> + * @param t The listener instance to add
> *
> + * @throws ClassCastException If the class of the listener instance does not implement
> + * {@link EventListener} or a subinterface recognized by the servlet
> + * container, or if a non-standard listener type is not packaged in a JAR
> + * file with a <code>listener</code> element in the
> + * <code>META-INF/services</code> directory
> + * @throws IllegalArgumentException If the lifecycle of a listener prohibits addition at runtime, or if the
> + * class has a {@link jakarta.servlet.annotation.WebListener} annotation
> + * that conflicts with the programmatic addition
> + * @throws IllegalStateException If the context has already been initialised
> * @throws UnsupportedOperationException If called from a
> * {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> * method of a {@link ServletContextListener} that was not defined in a
> @@ -770,10 +795,19 @@ public interface ServletContext {
> <T extends EventListener> void addListener(T t);
>
> /**
> - * TODO SERVLET3 - Add comments
> + * Adds a listener to this web application. The listener instance will be created by the container using the
> + * no-argument constructor of the given class.
> *
> - * @param listenerClass TODO
> + * @param listenerClass The class of the listener to add
> *
> + * @throws ClassCastException If the class does not implement {@link EventListener} or a subinterface
> + * recognized by the servlet container, or if a non-standard listener type
> + * is not packaged in a JAR file with a <code>listener</code> element in
> + * the <code>META-INF/services</code> directory
> + * @throws IllegalArgumentException If the lifecycle of a listener prohibits addition at runtime, or if the
> + * class has a {@link jakarta.servlet.annotation.WebListener} annotation
> + * that conflicts with the programmatic addition
> + * @throws IllegalStateException If the context has already been initialised
> * @throws UnsupportedOperationException If called from a
> * {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> * method of a {@link ServletContextListener} that was not defined in a
> @@ -787,14 +821,15 @@ public interface ServletContext {
> void addListener(Class<? extends EventListener> listenerClass);
>
> /**
> - * TODO SERVLET3 - Add comments
> + * Creates a new instance of the given listener class, using the web application class loader.
> *
> - * @param <T> TODO
> - * @param c TODO
> + * @param <T> The type of listener being created
> + * @param c The class of the listener to create
> *
> - * @return TODO
> + * @return The new listener instance
> *
> - * @throws ServletException TODO
> + * @throws ServletException If the listener cannot be instantiated, e.g., if the class does not have a
> + * no-argument constructor, or if instantiation fails for any other reason
> * @throws UnsupportedOperationException If called from a
> * {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> * method of a {@link ServletContextListener} that was not defined in a
> @@ -808,9 +843,12 @@ public interface ServletContext {
> <T extends EventListener> T createListener(Class<T> c) throws ServletException;
>
> /**
> - * @return TODO
> + * Returns the {@link JspConfigDescriptor} for this web application, which provides access to the JSP configuration
> + * elements such as taglib and jsp-property-group declarations.
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @return The {@link JspConfigDescriptor} for this web application
> + *
> + * @since Servlet 3.0
> */
> JspConfigDescriptor getJspConfigDescriptor();
>
> diff --git a/java/jakarta/servlet/ServletRequest.java b/java/jakarta/servlet/ServletRequest.java
> index 749a9fc567..dea5715bd0 100644
> --- a/java/jakarta/servlet/ServletRequest.java
> +++ b/java/jakarta/servlet/ServletRequest.java
> @@ -441,54 +441,66 @@ public interface ServletRequest {
> int getLocalPort();
>
> /**
> - * @return TODO
> + * Returns the {@link ServletContext} to which this servlet belongs.
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @return the ServletContext associated with this request
> + *
> + * @since Servlet 3.0
> */
> ServletContext getServletContext();
>
> /**
> - * @return TODO
> + * Initiates asynchronous processing for this request. The asynchronous processing is performed using the current
> + * request and response objects.
> + *
> + * @return an {@link AsyncContext} instance for managing the asynchronous processing
> *
> - * @throws IllegalStateException If async is not supported for this request
> + * @throws IllegalStateException if async is not supported for this request
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @since Servlet 3.0
> */
> AsyncContext startAsync() throws IllegalStateException;
>
> /**
> - * @param servletRequest The ServletRequest with which to initialise the asynchronous context
> - * @param servletResponse The ServletResponse with which to initialise the asynchronous context
> + * Initiates asynchronous processing for this request using the specified request and response objects.
> + *
> + * @param servletRequest the ServletRequest with which to initialise the asynchronous context
> + * @param servletResponse the ServletResponse with which to initialise the asynchronous context
> *
> - * @return TODO
> + * @return an {@link AsyncContext} instance for managing the asynchronous processing
> *
> - * @throws IllegalStateException If async is not supported for this request
> + * @throws IllegalStateException if async is not supported for this request
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @since Servlet 3.0
> */
> AsyncContext startAsync(ServletRequest servletRequest, ServletResponse servletResponse)
> throws IllegalStateException;
>
> /**
> - * @return TODO
> + * Returns whether asynchronous processing has been started for this request.
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @return {@code true} if asynchronous processing has been started, {@code false} otherwise
> + *
> + * @since Servlet 3.0
> */
> boolean isAsyncStarted();
>
> /**
> - * @return TODO
> + * Returns whether asynchronous processing is supported for this request and has not already been started.
> + *
> + * @return {@code true} if asynchronous processing is supported and has not yet been started, {@code false}
> + * otherwise
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @since Servlet 3.0
> */
> boolean isAsyncSupported();
>
> /**
> - * Get the current AsyncContext.
> + * Returns the current {@link AsyncContext} associated with this request.
> *
> - * @return The current AsyncContext
> + * @return the current AsyncContext
> *
> - * @throws IllegalStateException if the request is not in asynchronous mode (i.e. @link #isAsyncStarted() is
> + * @throws IllegalStateException if the request is not in asynchronous mode (i.e. {@link #isAsyncStarted()} is
> * {@code false})
> *
> * @since Servlet 3.0
> @@ -496,9 +508,12 @@ public interface ServletRequest {
> AsyncContext getAsyncContext();
>
> /**
> - * @return TODO
> + * Returns the {@link DispatcherType} that represents the type of dispatch (REQUEST, FORWARD, INCLUDE, ERROR, or
> + * ASYNC) through which this request was initiated.
> + *
> + * @return the DispatcherType for this request
> *
> - * @since Servlet 3.0 TODO SERVLET3 - Add comments
> + * @since Servlet 3.0
> */
> DispatcherType getDispatcherType();
>
> diff --git a/java/jakarta/servlet/ServletRequestWrapper.java b/java/jakarta/servlet/ServletRequestWrapper.java
> index af003a0cc7..769aa13e3e 100644
> --- a/java/jakarta/servlet/ServletRequestWrapper.java
> +++ b/java/jakarta/servlet/ServletRequestWrapper.java
> @@ -164,7 +164,7 @@ public class ServletRequestWrapper implements ServletRequest {
> * The default behavior of this method is to return getParameterMap() on the wrapped request object.
> */
> @Override
> - public Map<String,String[]> getParameterMap() {
> + public Map<String, String[]> getParameterMap() {
> return this.request.getParameterMap();
> }
>
> @@ -400,7 +400,8 @@ public class ServletRequestWrapper implements ServletRequest {
> }
>
> /**
> - * TODO SERVLET3 - Add comments
> + * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
> + * given request, then return <code>true</code>. Otherwise return <code>false</code>.
> *
> * @param wrapped The request to compare to the wrapped request
> *
> @@ -420,7 +421,8 @@ public class ServletRequestWrapper implements ServletRequest {
> }
>
> /**
> - * TODO SERVLET3 - Add comments
> + * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
> + * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
> *
> * @param wrappedType The class to compare to the class of the wrapped request
> *
> diff --git a/java/jakarta/servlet/ServletResponseWrapper.java b/java/jakarta/servlet/ServletResponseWrapper.java
> index 94c4e5ac01..4f9b2b5c4f 100644
> --- a/java/jakarta/servlet/ServletResponseWrapper.java
> +++ b/java/jakarta/servlet/ServletResponseWrapper.java
> @@ -221,7 +221,8 @@ public class ServletResponseWrapper implements ServletResponse {
> }
>
> /**
> - * TODO SERVLET3 - Add comments
> + * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
> + * given response, then return <code>true</code>. Otherwise return <code>false</code>.
> *
> * @param wrapped The response to compare to the wrapped response
> *
> @@ -241,7 +242,8 @@ public class ServletResponseWrapper implements ServletResponse {
> }
>
> /**
> - * TODO SERVLET3 - Add comments
> + * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
> + * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
> *
> * @param wrappedType The class to compare to the class of the wrapped response
> *
> diff --git a/java/jakarta/servlet/annotation/HandlesTypes.java b/java/jakarta/servlet/annotation/HandlesTypes.java
> index 7dd52b165c..203340c8b9 100644
> --- a/java/jakarta/servlet/annotation/HandlesTypes.java
> +++ b/java/jakarta/servlet/annotation/HandlesTypes.java
> @@ -31,9 +31,11 @@ import java.lang.annotation.Target;
> @Retention(RetentionPolicy.RUNTIME)
> public @interface HandlesTypes {
>
> - /**
> - * @return array of classes
> - */
> + /**
> + * Declares the classes handled by the {@link jakarta.servlet.ServletContainerInitializer}.
> + *
> + * @return array of classes
> + */
> Class<?>[] value();
>
> }
> diff --git a/java/jakarta/servlet/annotation/MultipartConfig.java b/java/jakarta/servlet/annotation/MultipartConfig.java
> index 0558b7dfd4..d0538bf954 100644
> --- a/java/jakarta/servlet/annotation/MultipartConfig.java
> +++ b/java/jakarta/servlet/annotation/MultipartConfig.java
> @@ -41,22 +41,31 @@ import java.lang.annotation.Target;
> public @interface MultipartConfig {
>
> /**
> + * Specifies the location in which the Container stores temporary files.
> + *
> * @return location in which the Container stores temporary files
> */
> String location() default "";
>
> /**
> + * Specifies the maximum size allowed for uploaded files.
> + *
> * @return the maximum size allowed for uploaded files (in bytes)
> */
> long maxFileSize() default -1L;
>
> /**
> + * Specifies the maximum size of the request allowed for {@code
> + * multipart/form-data}.
> + *
> * @return the maximum size of the request allowed for {@code
> * multipart/form-data}
> */
> long maxRequestSize() default -1L;
>
> /**
> + * Specifies the size threshold in bytes after which the file will be written to disk.
> + *
> * @return the size threshold at which the file will be written to the disk
> */
> int fileSizeThreshold() default 0;
> diff --git a/java/jakarta/servlet/annotation/WebFilter.java b/java/jakarta/servlet/annotation/WebFilter.java
> index a277d43788..d23d9f2b0e 100644
> --- a/java/jakarta/servlet/annotation/WebFilter.java
> +++ b/java/jakarta/servlet/annotation/WebFilter.java
> @@ -50,36 +50,50 @@ import jakarta.servlet.DispatcherType;
> public @interface WebFilter {
>
> /**
> + * Provides a description of the Filter.
> + *
> * @return description of the Filter, if present
> */
> String description() default "";
>
> /**
> + * Provides a display name for the Filter.
> + *
> * @return display name of the Filter, if present
> */
> String displayName() default "";
>
> /**
> + * Declares initialization parameters for the Filter.
> + *
> * @return array of initialization params for this Filter
> */
> WebInitParam[] initParams() default {};
>
> /**
> + * Declares the name of the Filter.
> + *
> * @return name of the Filter, if present
> */
> String filterName() default "";
>
> /**
> + * Provides a small icon for the Filter.
> + *
> * @return small icon for this Filter, if present
> */
> String smallIcon() default "";
>
> /**
> + * Provides a large icon for the Filter.
> + *
> * @return the large icon for this Filter, if present
> */
> String largeIcon() default "";
>
> /**
> + * Declares the servlet names to which this Filter applies.
> + *
> * @return array of Servlet names to which this Filter applies
> */
> String[] servletNames() default {};
> @@ -94,17 +108,23 @@ public @interface WebFilter {
> String[] value() default {};
>
> /**
> + * Declares the URL patterns to which this Filter applies.
> + *
> * @return array of URL patterns to which this Filter applies
> */
> String[] urlPatterns() default {};
>
> /**
> + * Declares the dispatcher types to which this Filter applies.
> + *
> * @return array of DispatcherTypes to which this filter applies
> */
> DispatcherType[] dispatcherTypes() default { DispatcherType.REQUEST };
>
> /**
> - * @return asynchronous operation supported by this Filter
> + * Declares whether asynchronous operation is supported by this Filter.
> + *
> + * @return {@code true} if asynchronous operation is supported, {@code false} otherwise
> */
> boolean asyncSupported() default false;
> }
> diff --git a/java/jakarta/servlet/annotation/WebInitParam.java b/java/jakarta/servlet/annotation/WebInitParam.java
> index feb4bf901b..d541fa7cff 100644
> --- a/java/jakarta/servlet/annotation/WebInitParam.java
> +++ b/java/jakarta/servlet/annotation/WebInitParam.java
> @@ -39,16 +39,22 @@ import java.lang.annotation.Target;
> public @interface WebInitParam {
>
> /**
> + * The name of the initialization parameter.
> + *
> * @return name of the initialization parameter
> */
> String name();
>
> /**
> + * The value of the initialization parameter.
> + *
> * @return value of the initialization parameter
> */
> String value();
>
> /**
> + * A description of the initialization parameter.
> + *
> * @return description of the initialization parameter
> */
> String description() default "";
> diff --git a/java/jakarta/servlet/annotation/WebListener.java b/java/jakarta/servlet/annotation/WebListener.java
> index aee671b4fa..d01a2d658d 100644
> --- a/java/jakarta/servlet/annotation/WebListener.java
> +++ b/java/jakarta/servlet/annotation/WebListener.java
> @@ -41,6 +41,8 @@ import java.lang.annotation.Target;
> public @interface WebListener {
>
> /**
> + * Provides a description of the listener.
> + *
> * @return description of the listener, if present
> */
> String value() default "";
> diff --git a/java/jakarta/servlet/annotation/WebServlet.java b/java/jakarta/servlet/annotation/WebServlet.java
> index 5e1334bd1e..ed12b5b1a3 100644
> --- a/java/jakarta/servlet/annotation/WebServlet.java
> +++ b/java/jakarta/servlet/annotation/WebServlet.java
> @@ -46,57 +46,75 @@ import java.lang.annotation.Target;
> @Documented
> public @interface WebServlet {
>
> - /**
> - * @return name of the Servlet
> - */
> + /**
> + * Provides the name of this servlet.
> + *
> + * @return name of the Servlet
> + */
> String name() default "";
>
> - /**
> - * A convenience method, to allow extremely simple annotation of a class.
> - *
> - * @return array of URL patterns
> - *
> - * @see #urlPatterns()
> - */
> + /**
> + * A convenience method, to allow extremely simple annotation of a class.
> + *
> + * @return array of URL patterns
> + *
> + * @see #urlPatterns()
> + */
> String[] value() default {};
>
> - /**
> - * @return array of URL patterns to which this Filter applies
> - */
> + /**
> + * Declares the URL patterns for this servlet.
> + *
> + * @return array of URL patterns to which this Servlet applies
> + */
> String[] urlPatterns() default {};
>
> - /**
> - * @return load on startup ordering hint
> - */
> + /**
> + * Provides a load-on-startup ordering hint for this servlet.
> + *
> + * @return load on startup ordering hint
> + */
> int loadOnStartup() default -1;
>
> - /**
> - * @return array of initialization params for this Servlet
> - */
> + /**
> + * Declares initialization parameters for this servlet.
> + *
> + * @return array of initialization params for this Servlet
> + */
> WebInitParam[] initParams() default {};
>
> - /**
> - * @return asynchronous operation supported by this Servlet
> - */
> + /**
> + * Indicates whether this servlet supports asynchronous operation.
> + *
> + * @return asynchronous operation supported by this Servlet
> + */
> boolean asyncSupported() default false;
>
> - /**
> - * @return small icon for this Servlet, if present
> - */
> + /**
> + * Provides the URL of a small icon for this servlet.
> + *
> + * @return small icon for this Servlet, if present
> + */
> String smallIcon() default "";
>
> - /**
> - * @return large icon for this Servlet, if present
> - */
> + /**
> + * Provides the URL of a large icon for this servlet.
> + *
> + * @return large icon for this Servlet, if present
> + */
> String largeIcon() default "";
>
> - /**
> - * @return description of this Servlet, if present
> - */
> + /**
> + * Provides a description of this servlet.
> + *
> + * @return description of this Servlet, if present
> + */
> String description() default "";
>
> - /**
> - * @return display name of this Servlet, if present
> - */
> + /**
> + * Provides a display name for this servlet.
> + *
> + * @return display name of this Servlet, if present
> + */
> String displayName() default "";
> }
> diff --git a/java/jakarta/servlet/http/HttpFilter.java b/java/jakarta/servlet/http/HttpFilter.java
> index a4cbf8208a..85070f9f58 100644
> --- a/java/jakarta/servlet/http/HttpFilter.java
> +++ b/java/jakarta/servlet/http/HttpFilter.java
> @@ -34,6 +34,13 @@ public abstract class HttpFilter extends GenericFilter {
> @Serial
> private static final long serialVersionUID = 1L;
>
> + /**
> + * Constructs a new HttpFilter.
> + */
> + public HttpFilter() {
> + // NO-OP
> + }
> +
> /**
> * {@inheritDoc} This implementation tests the request and response to see if they are instances of
> * {@link HttpServletRequest} and {@link HttpServletResponse} respectively. If they are then they are passed to
> diff --git a/java/jakarta/servlet/http/HttpServletMapping.java b/java/jakarta/servlet/http/HttpServletMapping.java
> index ae88d321de..aece46c8e8 100644
> --- a/java/jakarta/servlet/http/HttpServletMapping.java
> +++ b/java/jakarta/servlet/http/HttpServletMapping.java
> @@ -25,25 +25,33 @@ import jakarta.servlet.annotation.WebServlet;
> */
> public interface HttpServletMapping {
>
> - /**
> - * @return The value that was matched or the empty String if not known.
> - */
> + /**
> + * Returns the value that was matched when mapping the request to the servlet.
> + *
> + * @return The value that was matched or the empty String if not known.
> + */
> String getMatchValue();
>
> - /**
> - * @return The {@code url-pattern} that matched this request or the empty String if not known.
> - */
> + /**
> + * Returns the URL pattern that matched this request.
> + *
> + * @return The {@code url-pattern} that matched this request or the empty String if not known.
> + */
> String getPattern();
>
> - /**
> - * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
> - * {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
> - * <code>addServlet()</code> methods) that the request was mapped to.
> - */
> + /**
> + * Returns the name of the servlet to which the request was mapped.
> + *
> + * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
> + * {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
> + * <code>addServlet()</code> methods) that the request was mapped to.
> + */
> String getServletName();
>
> - /**
> - * @return The type of match ({@code null} if not known)
> - */
> + /**
> + * Returns the type of match used to map the request to the servlet.
> + *
> + * @return The type of match ({@code null} if not known)
> + */
> MappingMatch getMappingMatch();
> }
> diff --git a/java/jakarta/servlet/http/PushBuilder.java b/java/jakarta/servlet/http/PushBuilder.java
> index 46c6ed72bc..0adbda4a69 100644
> --- a/java/jakarta/servlet/http/PushBuilder.java
> +++ b/java/jakarta/servlet/http/PushBuilder.java
> @@ -156,12 +156,16 @@ public interface PushBuilder {
> String getSessionId();
>
> /**
> + * Returns the set of names of HTTP headers that will be used the next time {@code push()} is called.
> + *
> * @return The current set of names of HTTP headers to be used the next time {@code push()} is called.
> */
> Set<String> getHeaderNames();
>
> /**
> - * Obtain a value for the given HTTP header. TODO Servlet 4.0 Clarify the behaviour of this method
> + * Obtain a value for the given HTTP header. If the push builder has not had this header set, the return value is
> + * <code>null</code>. If the push builder has had this header set multiple times, the value returned is
> + * implementation-specific.
> *
> * @param name The name of the header whose value is to be returned
> *
> diff --git a/java/jakarta/transaction/HeuristicCommitException.java b/java/jakarta/transaction/HeuristicCommitException.java
> index 1c56f380d8..8f1e2e63a6 100644
> --- a/java/jakarta/transaction/HeuristicCommitException.java
> +++ b/java/jakarta/transaction/HeuristicCommitException.java
> @@ -18,15 +18,29 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when a transaction has been heuristically committed. A heuristic
> + * commit indicates that the transaction manager has committed the transaction
> + * without full agreement from all resource managers, typically as a result of
> + * a failure during the commit process.
> + */
> public class HeuristicCommitException extends Exception {
>
> @Serial
> private static final long serialVersionUID = -3977609782149921760L;
>
> + /**
> + * Constructs a {@code HeuristicCommitException} with no detail message.
> + */
> public HeuristicCommitException() {
> super();
> }
>
> + /**
> + * Constructs a {@code HeuristicCommitException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public HeuristicCommitException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/HeuristicMixedException.java b/java/jakarta/transaction/HeuristicMixedException.java
> index 50b86867a3..fbc2a93eff 100644
> --- a/java/jakarta/transaction/HeuristicMixedException.java
> +++ b/java/jakarta/transaction/HeuristicMixedException.java
> @@ -18,15 +18,29 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when a transaction has been heuristically committed in part and
> + * heuristically rolled back in part. A heuristic mixed result indicates that
> + * some resource managers committed the transaction while others rolled it
> + * back, typically as a result of a failure during the commit process.
> + */
> public class HeuristicMixedException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 2345014349685956666L;
>
> + /**
> + * Constructs a {@code HeuristicMixedException} with no detail message.
> + */
> public HeuristicMixedException() {
> super();
> }
>
> + /**
> + * Constructs a {@code HeuristicMixedException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public HeuristicMixedException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/HeuristicRollbackException.java b/java/jakarta/transaction/HeuristicRollbackException.java
> index 2ee7cc6bf5..0aa897539b 100644
> --- a/java/jakarta/transaction/HeuristicRollbackException.java
> +++ b/java/jakarta/transaction/HeuristicRollbackException.java
> @@ -18,15 +18,29 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when a transaction has been heuristically rolled back. A heuristic
> + * rollback indicates that the transaction manager has rolled back the
> + * transaction without full agreement from all resource managers, typically
> + * as a result of a failure during the commit process.
> + */
> public class HeuristicRollbackException extends Exception {
>
> @Serial
> private static final long serialVersionUID = -3483618944556408897L;
>
> + /**
> + * Constructs a {@code HeuristicRollbackException} with no detail message.
> + */
> public HeuristicRollbackException() {
> super();
> }
>
> + /**
> + * Constructs a {@code HeuristicRollbackException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public HeuristicRollbackException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/InvalidTransactionException.java b/java/jakarta/transaction/InvalidTransactionException.java
> index 97e0476ab1..d8b1e12ce6 100644
> --- a/java/jakarta/transaction/InvalidTransactionException.java
> +++ b/java/jakarta/transaction/InvalidTransactionException.java
> @@ -18,15 +18,28 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when a transaction is invalid. This exception indicates that the
> + * transaction on which an operation was attempted is no longer valid, for
> + * example because it has already completed or been rolled back.
> + */
> public class InvalidTransactionException extends java.rmi.RemoteException {
>
> @Serial
> private static final long serialVersionUID = 3597320220337691496L;
>
> + /**
> + * Constructs an {@code InvalidTransactionException} with no detail message.
> + */
> public InvalidTransactionException() {
> super();
> }
>
> + /**
> + * Constructs an {@code InvalidTransactionException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public InvalidTransactionException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/NotSupportedException.java b/java/jakarta/transaction/NotSupportedException.java
> index 073ce36240..263a44f852 100644
> --- a/java/jakarta/transaction/NotSupportedException.java
> +++ b/java/jakarta/transaction/NotSupportedException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when a requested operation is not supported.
> + */
> public class NotSupportedException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 56870312332816390L;
>
> + /**
> + * Constructs a {@code NotSupportedException} with no detail message.
> + */
> public NotSupportedException() {
> super();
> }
>
> + /**
> + * Constructs a {@code NotSupportedException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public NotSupportedException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/RollbackException.java b/java/jakarta/transaction/RollbackException.java
> index f0b1d0b887..7b6beb84be 100644
> --- a/java/jakarta/transaction/RollbackException.java
> +++ b/java/jakarta/transaction/RollbackException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when a transaction must be rolled back.
> + */
> public class RollbackException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 4151607774785285395L;
>
> + /**
> + * Constructs a {@code RollbackException} with no detail message.
> + */
> public RollbackException() {
> super();
> }
>
> + /**
> + * Constructs a {@code RollbackException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public RollbackException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/Status.java b/java/jakarta/transaction/Status.java
> index 9b113fc406..d05176b77f 100644
> --- a/java/jakarta/transaction/Status.java
> +++ b/java/jakarta/transaction/Status.java
> @@ -16,15 +16,48 @@
> */
> package jakarta.transaction;
>
> +/**
> + * Defines the set of status constants for a transaction.
> + */
> public interface Status {
> + /**
> + * The transaction is active and work is in progress.
> + */
> int STATUS_ACTIVE = 0;
> + /**
> + * The transaction has been marked for rollback only.
> + */
> int STATUS_MARKED_ROLLBACK = 1;
> + /**
> + * The transaction resources have been prepared and are awaiting completion.
> + */
> int STATUS_PREPARED = 2;
> + /**
> + * The transaction has been committed successfully.
> + */
> int STATUS_COMMITTED = 3;
> + /**
> + * The transaction has been rolled back.
> + */
> int STATUS_ROLLEDBACK = 4;
> + /**
> + * The transaction status is unknown.
> + */
> int STATUS_UNKNOWN = 5;
> + /**
> + * There is no active transaction for the current thread.
> + */
> int STATUS_NO_TRANSACTION = 6;
> + /**
> + * The transaction manager is in the process of preparing the transaction resources.
> + */
> int STATUS_PREPARING = 7;
> + /**
> + * The transaction manager is in the process of committing the transaction.
> + */
> int STATUS_COMMITTING = 8;
> + /**
> + * The transaction manager is in the process of rolling back the transaction.
> + */
> int STATUS_ROLLING_BACK = 9;
> }
> diff --git a/java/jakarta/transaction/Synchronization.java b/java/jakarta/transaction/Synchronization.java
> index b188911cda..c9b20d0555 100644
> --- a/java/jakarta/transaction/Synchronization.java
> +++ b/java/jakarta/transaction/Synchronization.java
> @@ -16,8 +16,25 @@
> */
> package jakarta.transaction;
>
> +/**
> + * Callback interface for notification of transaction completion.
> + * Registered with a transaction so that the implementing object is
> + * notified when the transaction is about to complete and when it has
> + * completed.
> + */
> public interface Synchronization {
> + /**
> + * Called before the transaction is committed or rolled back.
> + * This method is invoked after all work on the transaction has
> + * been completed but before the commit or rollback is performed.
> + */
> void beforeCompletion();
>
> + /**
> + * Called after the transaction has completed.
> + *
> + * @param status the status of the transaction, one of the
> + * {@link Status} constants
> + */
> void afterCompletion(int status);
> }
> diff --git a/java/jakarta/transaction/SystemException.java b/java/jakarta/transaction/SystemException.java
> index 5c3bd33492..9b9a71d424 100644
> --- a/java/jakarta/transaction/SystemException.java
> +++ b/java/jakarta/transaction/SystemException.java
> @@ -18,21 +18,42 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown to indicate a system error during transaction processing.
> + * When this exception is thrown, the state of the transaction is
> + * unknown and may need to be rolled back.
> + */
> public class SystemException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 8615483418828223571L;
>
> + /**
> + * The error code associated with this exception.
> + */
> public int errorCode;
>
> + /**
> + * Constructs a {@code SystemException} with no detail message.
> + */
> public SystemException() {
> super();
> }
>
> + /**
> + * Constructs a {@code SystemException} with the specified detail message.
> + *
> + * @param s the detail message
> + */
> public SystemException(String s) {
> super(s);
> }
>
> + /**
> + * Constructs a {@code SystemException} with the specified error code.
> + *
> + * @param errcode the error code
> + */
> public SystemException(int errcode) {
> super();
> errorCode = errcode;
> diff --git a/java/jakarta/transaction/Transaction.java b/java/jakarta/transaction/Transaction.java
> index 1f031d2a8b..626786afa8 100644
> --- a/java/jakarta/transaction/Transaction.java
> +++ b/java/jakarta/transaction/Transaction.java
> @@ -18,21 +18,84 @@ package jakarta.transaction;
>
> import javax.transaction.xa.XAResource;
>
> +/**
> + * Represents an active transaction.
> + * Provides methods for committing, rolling back, and managing
> + * resources enlisted in the transaction.
> + */
> public interface Transaction {
>
> + /**
> + * Commits the transaction.
> + *
> + * @throws RollbackException if the transaction has been marked for rollback only
> + * @throws HeuristicMixedException if the transaction was heuristically
> + * partitioned, with some resources committed and others rolled back
> + * @throws HeuristicRollbackException if the transaction was heuristically rolled back
> + * @throws SecurityException if the caller is not authorized to commit
> + * @throws IllegalStateException if the transaction is not active
> + * @throws SystemException if a system error occurred
> + */
> void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
> IllegalStateException, SystemException;
>
> + /**
> + * Delists the specified XA resource from this transaction.
> + *
> + * @param xaRes the XA resource to delist
> + * @param flag one of {@code TMSUCCESS}, {@code TMFAIL}, or {@code TMSTARTEPOCH}
> + * @return {@code true} if the resource was delisted, {@code false} otherwise
> + * @throws IllegalStateException if the transaction is not active
> + * @throws SystemException if a system error occurred
> + */
> boolean delistResource(XAResource xaRes, int flag) throws IllegalStateException, SystemException;
>
> + /**
> + * Enlists the specified XA resource with this transaction.
> + *
> + * @param xaRes the XA resource to enlist
> + *
> + * @return {@code true} if the resource was enlisted, {@code false} otherwise
> + *
> + * @throws RollbackException if the transaction has been marked for rollback only
> + * @throws IllegalStateException if the transaction is not active or the
> + * resource is already enlisted
> + * @throws SystemException if a system error occurred
> + */
> boolean enlistResource(XAResource xaRes) throws RollbackException, IllegalStateException, SystemException;
>
> + /**
> + * Returns the status of this transaction.
> + *
> + * @return the transaction status, one of the {@link Status} constants
> + * @throws SystemException if a system error occurred
> + */
> int getStatus() throws SystemException;
>
> + /**
> + * Registers a synchronization callback with this transaction.
> + *
> + * @param sync the synchronization callback to register
> + * @throws RollbackException if the transaction has been marked for rollback only
> + * @throws IllegalStateException if the transaction is not active
> + * @throws SystemException if a system error occurred
> + */
> void registerSynchronization(Synchronization sync) throws RollbackException, IllegalStateException, SystemException;
>
> + /**
> + * Rolls back the transaction.
> + *
> + * @throws IllegalStateException if the transaction is not active
> + * @throws SystemException if a system error occurred
> + */
> void rollback() throws IllegalStateException, SystemException;
>
> + /**
> + * Marks this transaction so that the only valid outcome is a rollback.
> + *
> + * @throws IllegalStateException if the transaction is not active
> + * @throws SystemException if a system error occurred
> + */
> void setRollbackOnly() throws IllegalStateException, SystemException;
>
> }
> diff --git a/java/jakarta/transaction/TransactionManager.java b/java/jakarta/transaction/TransactionManager.java
> index 2bd58e16c8..633b3775ca 100644
> --- a/java/jakarta/transaction/TransactionManager.java
> +++ b/java/jakarta/transaction/TransactionManager.java
> @@ -16,23 +16,91 @@
> */
> package jakarta.transaction;
>
> +/**
> + * Provides methods for managing transactions.
> + * Used by the transaction manager to begin, commit, and roll back
> + * transactions, and to suspend and resume them.
> + */
> public interface TransactionManager {
> + /**
> + * Begins a new transaction for the current thread.
> + *
> + * @throws NotSupportedException if the transaction manager does not
> + * support transactions
> + * @throws SystemException if a system error occurred
> + */
> void begin() throws NotSupportedException, SystemException;
>
> + /**
> + * Commits the transaction associated with the current thread.
> + *
> + * @throws RollbackException if the transaction has been marked for rollback only
> + * @throws HeuristicMixedException if the transaction was heuristically
> + * partitioned
> + * @throws HeuristicRollbackException if the transaction was heuristically rolled back
> + * @throws SecurityException if the caller is not authorized to commit
> + * @throws IllegalStateException if no transaction is active
> + * @throws SystemException if a system error occurred
> + */
> void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
> IllegalStateException, SystemException;
>
> + /**
> + * Returns the status of the transaction associated with the current thread.
> + *
> + * @return the transaction status, one of the {@link Status} constants
> + * @throws SystemException if a system error occurred
> + */
> int getStatus() throws SystemException;
>
> + /**
> + * Returns the {@link Transaction} object associated with the current thread.
> + *
> + * @return the current transaction, or {@code null} if there is no active transaction
> + * @throws SystemException if a system error occurred
> + */
> Transaction getTransaction() throws SystemException;
>
> + /**
> + * Resumes a previously suspended transaction for the current thread.
> + *
> + * @param tobj the transaction to resume
> + * @throws InvalidTransactionException if the transaction is no longer valid
> + * @throws IllegalStateException if there is already an active transaction
> + * @throws SystemException if a system error occurred
> + */
> void resume(Transaction tobj) throws InvalidTransactionException, IllegalStateException, SystemException;
>
> + /**
> + * Rolls back the transaction associated with the current thread.
> + *
> + * @throws IllegalStateException if no transaction is active
> + * @throws SecurityException if the caller is not authorized to roll back
> + * @throws SystemException if a system error occurred
> + */
> void rollback() throws IllegalStateException, SecurityException, SystemException;
>
> + /**
> + * Marks the current transaction so that the only valid outcome is a rollback.
> + *
> + * @throws IllegalStateException if no transaction is active
> + * @throws SystemException if a system error occurred
> + */
> void setRollbackOnly() throws IllegalStateException, SystemException;
>
> + /**
> + * Sets the default transaction timeout.
> + *
> + * @param seconds the timeout value in seconds
> + * @throws SystemException if a system error occurred
> + */
> void setTransactionTimeout(int seconds) throws SystemException;
>
> + /**
> + * Suspends the transaction associated with the current thread.
> + *
> + * @return the suspended transaction, or {@code null} if there was no active transaction
> + * @throws SystemException if a system error occurred
> + */
> Transaction suspend() throws SystemException;
> }
> diff --git a/java/jakarta/transaction/TransactionRequiredException.java b/java/jakarta/transaction/TransactionRequiredException.java
> index 32d7aef467..be6a2a6c1c 100644
> --- a/java/jakarta/transaction/TransactionRequiredException.java
> +++ b/java/jakarta/transaction/TransactionRequiredException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when an operation requires an active transaction but none exists.
> + */
> public class TransactionRequiredException extends java.rmi.RemoteException {
>
> @Serial
> private static final long serialVersionUID = -1898806419937446439L;
>
> + /**
> + * Constructs a {@code TransactionRequiredException} with no detail message.
> + */
> public TransactionRequiredException() {
> super();
> }
>
> + /**
> + * Constructs a {@code TransactionRequiredException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public TransactionRequiredException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/TransactionRolledbackException.java b/java/jakarta/transaction/TransactionRolledbackException.java
> index 3195c429e1..12bf91627a 100644
> --- a/java/jakarta/transaction/TransactionRolledbackException.java
> +++ b/java/jakarta/transaction/TransactionRolledbackException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
> import java.io.Serial;
>
> +/**
> + * Thrown when an operation is attempted on a transaction that has been rolled back.
> + */
> public class TransactionRolledbackException extends java.rmi.RemoteException {
>
> @Serial
> private static final long serialVersionUID = -3142798139623020577L;
>
> + /**
> + * Constructs a {@code TransactionRolledbackException} with no detail message.
> + */
> public TransactionRolledbackException() {
> super();
> }
>
> + /**
> + * Constructs a {@code TransactionRolledbackException} with the specified detail message.
> + *
> + * @param msg the detail message
> + */
> public TransactionRolledbackException(String msg) {
> super(msg);
> }
> diff --git a/java/jakarta/transaction/TransactionSynchronizationRegistry.java b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
> index b2ac98f3e2..1332cb07f0 100644
> --- a/java/jakarta/transaction/TransactionSynchronizationRegistry.java
> +++ b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
> @@ -16,18 +16,58 @@
> */
> package jakarta.transaction;
>
> +/**
> + * Provides a resource and transaction registry for resource managers.
> + * Allows resource managers to associate resources with the current
> + * transaction and register synchronization callbacks.
> + */
> public interface TransactionSynchronizationRegistry {
> + /**
> + * Returns the unique key identifying the current transaction.
> + *
> + * @return the transaction key, or {@code null} if there is no active transaction
> + */
> Object getTransactionKey();
>
> + /**
> + * Associates a resource with the given key in the current transaction context.
> + *
> + * @param key the key to associate with the resource
> + * @param value the resource object to associate
> + */
> void putResource(Object key, Object value);
>
> + /**
> + * Returns the resource associated with the given key in the current transaction context.
> + *
> + * @param key the key of the resource to retrieve
> + * @return the associated resource, or {@code null} if no resource is found
> + */
> Object getResource(Object key);
>
> + /**
> + * Registers an interposed synchronization callback with the current transaction.
> + *
> + * @param sync the synchronization callback to register
> + */
> void registerInterposedSynchronization(Synchronization sync);
>
> + /**
> + * Returns the status of the current transaction.
> + *
> + * @return the transaction status, one of the {@link Status} constants
> + */
> int getTransactionStatus();
>
> + /**
> + * Marks the current transaction so that the only valid outcome is a rollback.
> + */
> void setRollbackOnly();
>
> + /**
> + * Returns whether the current transaction has been marked for rollback only.
> + *
> + * @return {@code true} if the transaction is marked for rollback only
> + */
> boolean getRollbackOnly();
> }
> diff --git a/java/jakarta/transaction/UserTransaction.java b/java/jakarta/transaction/UserTransaction.java
> index 0506c9c102..04c558c0a4 100644
> --- a/java/jakarta/transaction/UserTransaction.java
> +++ b/java/jakarta/transaction/UserTransaction.java
> @@ -16,17 +16,64 @@
> */
> package jakarta.transaction;
>
> +/**
> + * Provides methods for managing user transactions.
> + * Allows application code to demarcate transaction boundaries explicitly.
> + */
> public interface UserTransaction {
> + /**
> + * Begins a new transaction for the current thread.
> + *
> + * @throws NotSupportedException if the transaction manager does not
> + * support transactions
> + * @throws SystemException if a system error occurred
> + */
> void begin() throws NotSupportedException, SystemException;
>
> + /**
> + * Commits the transaction associated with the current thread.
> + *
> + * @throws RollbackException if the transaction has been marked for rollback only
> + * @throws HeuristicMixedException if the transaction was heuristically
> + * partitioned
> + * @throws HeuristicRollbackException if the transaction was heuristically rolled back
> + * @throws SecurityException if the caller is not authorized to commit
> + * @throws IllegalStateException if no transaction is active
> + * @throws SystemException if a system error occurred
> + */
> void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
> IllegalStateException, SystemException;
>
> + /**
> + * Rolls back the transaction associated with the current thread.
> + *
> + * @throws IllegalStateException if no transaction is active
> + * @throws SecurityException if the caller is not authorized to roll back
> + * @throws SystemException if a system error occurred
> + */
> void rollback() throws IllegalStateException, SecurityException, SystemException;
>
> + /**
> + * Marks the current transaction so that the only valid outcome is a rollback.
> + *
> + * @throws IllegalStateException if no transaction is active
> + * @throws SystemException if a system error occurred
> + */
> void setRollbackOnly() throws IllegalStateException, SystemException;
>
> + /**
> + * Returns the status of the transaction associated with the current thread.
> + *
> + * @return the transaction status, one of the {@link Status} constants
> + * @throws SystemException if a system error occurred
> + */
> int getStatus() throws SystemException;
>
> + /**
> + * Sets the default transaction timeout.
> + *
> + * @param seconds the timeout value in seconds
> + * @throws SystemException if a system error occurred
> + */
> void setTransactionTimeout(int seconds) throws SystemException;
> }
> diff --git a/java/jakarta/websocket/ClientEndpoint.java b/java/jakarta/websocket/ClientEndpoint.java
> index acaa160cc8..6cfa8cbaa6 100644
> --- a/java/jakarta/websocket/ClientEndpoint.java
> +++ b/java/jakarta/websocket/ClientEndpoint.java
> @@ -23,14 +23,39 @@ import java.lang.annotation.Target;
>
> import jakarta.websocket.ClientEndpointConfig.Configurator;
>
> +/**
> + * Annotates a class as a WebSocket client endpoint. The annotation provides configuration
> + * information about the endpoint such as subprotocols, encoders, decoders, and configurator.
> + */
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.TYPE)
> public @interface ClientEndpoint {
> +
> + /**
> + * The sub-protocols that this client endpoint supports, in order of preference.
> + *
> + * @return The list of preferred sub-protocols
> + */
> String[] subprotocols() default {};
>
> + /**
> + * The decoder classes that this client endpoint uses.
> + *
> + * @return The list of decoder classes
> + */
> Class<? extends Decoder>[] decoders() default {};
>
> + /**
> + * The encoder classes that this client endpoint uses.
> + *
> + * @return The list of encoder classes
> + */
> Class<? extends Encoder>[] encoders() default {};
>
> + /**
> + * The configurator class used to customize the WebSocket handshake.
> + *
> + * @return The configurator class
> + */
> Class<? extends Configurator> configurator() default Configurator.class;
> }
> diff --git a/java/jakarta/websocket/ClientEndpointConfig.java b/java/jakarta/websocket/ClientEndpointConfig.java
> index 2af1f41575..05216b11e9 100644
> --- a/java/jakarta/websocket/ClientEndpointConfig.java
> +++ b/java/jakarta/websocket/ClientEndpointConfig.java
> @@ -22,22 +22,53 @@ import java.util.Map;
>
> import javax.net.ssl.SSLContext;
>
> +/**
> + * Provides configuration information for WebSocket client endpoints.
> + */
> public interface ClientEndpointConfig extends EndpointConfig {
>
> + /**
> + * Returns the list of sub-protocols that this client endpoint supports, in order of preference.
> + *
> + * @return The list of preferred sub-protocols
> + */
> List<String> getPreferredSubprotocols();
>
> + /**
> + * Returns the list of extensions that this client endpoint supports.
> + *
> + * @return The list of supported extensions
> + */
> List<Extension> getExtensions();
>
> + /**
> + * Returns the SSL context to use for secure WebSocket connections.
> + *
> + * @return The SSL context, or {@code null} if no custom SSL context is configured
> + */
> SSLContext getSSLContext();
>
> + /**
> + * Returns the configurator used to customize the WebSocket handshake.
> + *
> + * @return The configurator for this client endpoint
> + */
> Configurator getConfigurator();
>
> + /**
> + * Builder for creating {@link ClientEndpointConfig} instances.
> + */
> final class Builder {
>
> private static final Configurator DEFAULT_CONFIGURATOR = new Configurator() {
> };
>
>
> + /**
> + * Creates a new {@link Builder} instance for building a {@link ClientEndpointConfig}.
> + *
> + * @return A new builder instance
> + */
> public static Builder create() {
> return new Builder();
> }
> @@ -54,12 +85,23 @@ public interface ClientEndpointConfig extends EndpointConfig {
> private List<Class<? extends Decoder>> decoders = Collections.emptyList();
> private SSLContext sslContext = null;
>
> + /**
> + * Builds and returns a {@link ClientEndpointConfig} with the configured settings.
> + *
> + * @return The configured client endpoint configuration
> + */
> public ClientEndpointConfig build() {
> return new DefaultClientEndpointConfig(preferredSubprotocols, extensions, encoders, decoders, sslContext,
> configurator);
> }
>
>
> + /**
> + * Sets the configurator to use for the WebSocket handshake.
> + *
> + * @param configurator The configurator, or {@code null} to use the default
> + * @return This builder instance
> + */
> public Builder configurator(Configurator configurator) {
> if (configurator == null) {
> this.configurator = DEFAULT_CONFIGURATOR;
> @@ -70,6 +112,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the list of preferred sub-protocols for the WebSocket connection.
> + *
> + * @param preferredSubprotocols The list of sub-protocols in order of preference
> + * @return This builder instance
> + */
> public Builder preferredSubprotocols(List<String> preferredSubprotocols) {
> if (preferredSubprotocols == null || preferredSubprotocols.isEmpty()) {
> this.preferredSubprotocols = Collections.emptyList();
> @@ -80,6 +128,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the list of extensions to use for the WebSocket connection.
> + *
> + * @param extensions The list of extensions
> + * @return This builder instance
> + */
> public Builder extensions(List<Extension> extensions) {
> if (extensions == null || extensions.isEmpty()) {
> this.extensions = Collections.emptyList();
> @@ -90,6 +144,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the list of encoder classes to use for the WebSocket connection.
> + *
> + * @param encoders The list of encoder classes
> + * @return This builder instance
> + */
> public Builder encoders(List<Class<? extends Encoder>> encoders) {
> if (encoders == null || encoders.isEmpty()) {
> this.encoders = Collections.emptyList();
> @@ -100,6 +160,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the list of decoder classes to use for the WebSocket connection.
> + *
> + * @param decoders The list of decoder classes
> + * @return This builder instance
> + */
> public Builder decoders(List<Class<? extends Decoder>> decoders) {
> if (decoders == null || decoders.isEmpty()) {
> this.decoders = Collections.emptyList();
> @@ -110,6 +176,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the SSL context to use for secure WebSocket connections.
> + *
> + * @param sslContext The SSL context, or {@code null} for default SSL behavior
> + * @return This builder instance
> + */
> public Builder sslContext(SSLContext sslContext) {
> this.sslContext = sslContext;
> return this;
> @@ -117,8 +189,18 @@ public interface ClientEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Provides a mechanism to customize the WebSocket handshake for client endpoints.
> + * Applications may subclass this to inspect or modify the handshake.
> + */
> class Configurator {
>
> + /**
> + * Creates a new instance of the default Configurator.
> + */
> + public Configurator() {
> + }
> +
> /**
> * Provides the client with a mechanism to inspect and/or modify the headers that are sent to the server to
> * start the WebSocket handshake.
> diff --git a/java/jakarta/websocket/CloseReason.java b/java/jakarta/websocket/CloseReason.java
> index b7aef11305..7108dc6784 100644
> --- a/java/jakarta/websocket/CloseReason.java
> +++ b/java/jakarta/websocket/CloseReason.java
> @@ -16,20 +16,40 @@
> */
> package jakarta.websocket;
>
> +/**
> + * Represents the reason for the closure of a WebSocket connection, including a close code
> + * and an optional reason phrase.
> + */
> public class CloseReason {
>
> private final CloseCode closeCode;
> private final String reasonPhrase;
>
> + /**
> + * Creates a new CloseReason with the given close code and reason phrase.
> + *
> + * @param closeCode The close code
> + * @param reasonPhrase The reason phrase explaining the closure
> + */
> public CloseReason(CloseReason.CloseCode closeCode, String reasonPhrase) {
> this.closeCode = closeCode;
> this.reasonPhrase = reasonPhrase;
> }
>
> + /**
> + * Returns the close code.
> + *
> + * @return The close code
> + */
> public CloseCode getCloseCode() {
> return closeCode;
> }
>
> + /**
> + * Returns the reason phrase.
> + *
> + * @return The reason phrase
> + */
> public String getReasonPhrase() {
> return reasonPhrase;
> }
> @@ -39,34 +59,115 @@ public class CloseReason {
> return "CloseReason: code [" + closeCode.getCode() + "], reason [" + reasonPhrase + "]";
> }
>
> + /**
> + * Represents a WebSocket close code.
> + */
> public interface CloseCode {
> + /**
> + * Returns the numeric value of the close code.
> + *
> + * @return The numeric close code value
> + */
> int getCode();
> }
>
> + /**
> + * Standard WebSocket close codes as defined by RFC 6455 and related specifications.
> + */
> public enum CloseCodes implements CloseReason.CloseCode {
>
> + /**
> + * Indicates a normal closure, meaning that the purpose for which the connection was
> + * established has been fulfilled.
> + */
> NORMAL_CLOSURE(1000),
> + /**
> + * Indicates that the endpoint is going away, either because the browser is navigating
> + * away from the page, or because the server is shutting down.
> + */
> GOING_AWAY(1001),
> + /**
> + * Indicates that the endpoint is terminating the connection due to a protocol error.
> + */
> PROTOCOL_ERROR(1002),
> + /**
> + * Indicates that the endpoint is terminating the connection because it has received a
> + * type of data it cannot accept.
> + */
> CANNOT_ACCEPT(1003),
> + /**
> + * Reserved. The specific meaning might be defined in the future.
> + */
> RESERVED(1004),
> + /**
> + * Indicates that no status code was included in the closing frame. This value is
> + * reserved and must not be set as a status code in a Close control frame.
> + */
> NO_STATUS_CODE(1005),
> + /**
> + * Indicates that the connection was closed abnormally without receiving a close frame.
> + * This value is reserved and must not be set as a status code in a Close control frame.
> + */
> CLOSED_ABNORMALLY(1006),
> + /**
> + * Indicates that the endpoint is terminating the connection because it has received a
> + * message that contains data that is not consistent with the type of the message.
> + */
> NOT_CONSISTENT(1007),
> + /**
> + * Indicates that the endpoint is terminating the connection because it has received a
> + * message that violates its policy.
> + */
> VIOLATED_POLICY(1008),
> + /**
> + * Indicates that the endpoint is terminating the connection because it has received a
> + * message that is too big to process.
> + */
> TOO_BIG(1009),
> + /**
> + * Indicates that the client is terminating the connection because it expected the
> + * server to negotiate one or more extension, but the server didn't return them in the
> + * handshake response.
> + */
> NO_EXTENSION(1010),
> + /**
> + * Indicates that the server is terminating the connection because it encountered an
> + * unexpected condition that prevented it from fulfilling the request.
> + */
> UNEXPECTED_CONDITION(1011),
> + /**
> + * Indicates that the server is restarting. A client may choose to reconnect.
> + */
> SERVICE_RESTART(1012),
> + /**
> + * Indicates that the server is experiencing a temporary condition and the client should
> + * try to connect again later.
> + */
> TRY_AGAIN_LATER(1013),
> + /**
> + * Indicates that the connection was closed due to a failure to perform a TLS handshake.
> + * This value is reserved and must not be set as a status code in a Close control frame.
> + */
> TLS_HANDSHAKE_FAILURE(1015);
>
> private final int code;
>
> + /**
> + * Creates a close code with the given numeric value.
> + *
> + * @param code The numeric close code value
> + */
> CloseCodes(int code) {
> this.code = code;
> }
>
> + /**
> + * Returns the {@link CloseCode} for the given numeric code value.
> + *
> + * @param code The numeric close code value
> + * @return The corresponding {@link CloseCode}
> + * @throws IllegalArgumentException if the code is not a valid close code
> + */
> public static CloseCode getCloseCode(final int code) {
> if (code > 2999 && code < 5000) {
> return () -> code;
> @@ -91,6 +192,11 @@ public class CloseReason {
> };
> }
>
> + /**
> + * Returns the numeric value of this close code.
> + *
> + * @return The numeric close code value
> + */
> @Override
> public int getCode() {
> return code;
> diff --git a/java/jakarta/websocket/ContainerProvider.java b/java/jakarta/websocket/ContainerProvider.java
> index 56381d0dde..f79f7f8ed3 100644
> --- a/java/jakarta/websocket/ContainerProvider.java
> +++ b/java/jakarta/websocket/ContainerProvider.java
> @@ -24,6 +24,12 @@ import java.util.ServiceLoader;
> */
> public abstract class ContainerProvider {
>
> + /**
> + * Creates a new ContainerProvider instance.
> + */
> + protected ContainerProvider() {
> + }
> +
> private static final String DEFAULT_PROVIDER_CLASS_NAME = "org.apache.tomcat.websocket.WsWebSocketContainer";
>
> /**
> @@ -54,5 +60,10 @@ public abstract class ContainerProvider {
> return result;
> }
>
> + /**
> + * Returns the WebSocket container provided by this provider.
> + *
> + * @return The WebSocket container
> + */
> protected abstract WebSocketContainer getContainer();
> }
> diff --git a/java/jakarta/websocket/DecodeException.java b/java/jakarta/websocket/DecodeException.java
> index e6a9279094..d40fb4870f 100644
> --- a/java/jakarta/websocket/DecodeException.java
> +++ b/java/jakarta/websocket/DecodeException.java
> @@ -19,38 +19,83 @@ package jakarta.websocket;
> import java.io.Serial;
> import java.nio.ByteBuffer;
>
> +/**
> + * Exception thrown when a decoder fails to decode a WebSocket message.
> + */
> public class DecodeException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 1L;
>
> + /**
> + * The binary data that could not be decoded.
> + */
> private ByteBuffer bb;
> + /**
> + * The text data that could not be decoded.
> + */
> private String encodedString;
>
> + /**
> + * Creates a DecodeException for binary data with the specified detail message and cause.
> + *
> + * @param bb The binary data that could not be decoded
> + * @param message The detail message
> + * @param cause The underlying cause of the exception
> + */
> public DecodeException(ByteBuffer bb, String message, Throwable cause) {
> super(message, cause);
> this.bb = bb;
> }
>
> + /**
> + * Creates a DecodeException for text data with the specified detail message and cause.
> + *
> + * @param encodedString The text data that could not be decoded
> + * @param message The detail message
> + * @param cause The underlying cause of the exception
> + */
> public DecodeException(String encodedString, String message, Throwable cause) {
> super(message, cause);
> this.encodedString = encodedString;
> }
>
> + /**
> + * Creates a DecodeException for binary data with the specified detail message.
> + *
> + * @param bb The binary data that could not be decoded
> + * @param message The detail message
> + */
> public DecodeException(ByteBuffer bb, String message) {
> super(message);
> this.bb = bb;
> }
>
> + /**
> + * Creates a DecodeException for text data with the specified detail message.
> + *
> + * @param encodedString The text data that could not be decoded
> + * @param message The detail message
> + */
> public DecodeException(String encodedString, String message) {
> super(message);
> this.encodedString = encodedString;
> }
>
> + /**
> + * Returns the binary data that could not be decoded.
> + *
> + * @return The binary data, or {@code null} if the exception was for text data
> + */
> public ByteBuffer getBytes() {
> return bb;
> }
>
> + /**
> + * Returns the text data that could not be decoded.
> + *
> + * @return The text data, or {@code null} if the exception was for binary data
> + */
> public String getText() {
> return encodedString;
> }
> diff --git a/java/jakarta/websocket/Decoder.java b/java/jakarta/websocket/Decoder.java
> index 4f0a4e4c04..03db069e6a 100644
> --- a/java/jakarta/websocket/Decoder.java
> +++ b/java/jakarta/websocket/Decoder.java
> @@ -21,6 +21,10 @@ import java.io.InputStream;
> import java.io.Reader;
> import java.nio.ByteBuffer;
>
> +/**
> + * Base interface for WebSocket message decoders. Decoders convert incoming WebSocket messages
> + * from their raw form (text or binary) into application-specific objects.
> + */
> public interface Decoder {
>
> /**
> @@ -37,27 +41,91 @@ public interface Decoder {
> default void destroy() {
> }
>
> + /**
> + * A decoder that decodes entire binary WebSocket messages into an object of type T.
> + *
> + * @param <T> The type of object produced by the decoder
> + */
> interface Binary<T> extends Decoder {
>
> + /**
> + * Decodes the binary data into an object.
> + *
> + * @param bytes The binary data to decode
> + * @return The decoded object
> + * @throws DecodeException If the data cannot be decoded
> + */
> T decode(ByteBuffer bytes) throws DecodeException;
>
> + /**
> + * Determines whether this decoder can decode the given binary data.
> + *
> + * @param bytes The binary data to check
> + * @return {@code true} if this decoder can decode the data
> + */
> boolean willDecode(ByteBuffer bytes);
> }
>
> + /**
> + * A decoder that decodes entire binary WebSocket messages from an input stream into an
> + * object of type T.
> + *
> + * @param <T> The type of object produced by the decoder
> + */
> interface BinaryStream<T> extends Decoder {
>
> + /**
> + * Decodes the binary data from the input stream into an object.
> + *
> + * @param is The input stream containing the binary data
> + * @return The decoded object
> + * @throws DecodeException If the data cannot be decoded
> + * @throws IOException If an I/O error occurs
> + */
> T decode(InputStream is) throws DecodeException, IOException;
> }
>
> + /**
> + * A decoder that decodes entire text WebSocket messages into an object of type T.
> + *
> + * @param <T> The type of object produced by the decoder
> + */
> interface Text<T> extends Decoder {
>
> + /**
> + * Decodes the text data into an object.
> + *
> + * @param s The text data to decode
> + * @return The decoded object
> + * @throws DecodeException If the data cannot be decoded
> + */
> T decode(String s) throws DecodeException;
>
> + /**
> + * Determines whether this decoder can decode the given text data.
> + *
> + * @param s The text data to check
> + * @return {@code true} if this decoder can decode the data
> + */
> boolean willDecode(String s);
> }
>
> + /**
> + * A decoder that decodes entire text WebSocket messages from a reader into an object of
> + * type T.
> + *
> + * @param <T> The type of object produced by the decoder
> + */
> interface TextStream<T> extends Decoder {
>
> + /**
> + * Decodes the text data from the reader into an object.
> + *
> + * @param reader The reader containing the text data
> + * @return The decoded object
> + * @throws DecodeException If the data cannot be decoded
> + * @throws IOException If an I/O error occurs
> + */
> T decode(Reader reader) throws DecodeException, IOException;
> }
> }
> diff --git a/java/jakarta/websocket/DeploymentException.java b/java/jakarta/websocket/DeploymentException.java
> index d12f62680b..1bc0202cbd 100644
> --- a/java/jakarta/websocket/DeploymentException.java
> +++ b/java/jakarta/websocket/DeploymentException.java
> @@ -18,15 +18,29 @@ package jakarta.websocket;
>
> import java.io.Serial;
>
> +/**
> + * Exception thrown when a WebSocket endpoint cannot be deployed due to a configuration error.
> + */
> public class DeploymentException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 1L;
>
> + /**
> + * Creates a DeploymentException with the specified detail message.
> + *
> + * @param message The detail message
> + */
> public DeploymentException(String message) {
> super(message);
> }
>
> + /**
> + * Creates a DeploymentException with the specified detail message and cause.
> + *
> + * @param message The detail message
> + * @param cause The underlying cause of the exception
> + */
> public DeploymentException(String message, Throwable cause) {
> super(message, cause);
> }
> diff --git a/java/jakarta/websocket/EncodeException.java b/java/jakarta/websocket/EncodeException.java
> index 406b0ffee1..86b78c29d1 100644
> --- a/java/jakarta/websocket/EncodeException.java
> +++ b/java/jakarta/websocket/EncodeException.java
> @@ -18,23 +18,47 @@ package jakarta.websocket;
>
> import java.io.Serial;
>
> +/**
> + * Exception thrown when an encoder fails to encode an object as a WebSocket message.
> + */
> public class EncodeException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 1L;
>
> + /**
> + * The object that could not be encoded.
> + */
> private final Object object;
>
> + /**
> + * Creates an EncodeException with the specified object and detail message.
> + *
> + * @param object The object that could not be encoded
> + * @param message The detail message
> + */
> public EncodeException(Object object, String message) {
> super(message);
> this.object = object;
> }
>
> + /**
> + * Creates an EncodeException with the specified object, detail message, and cause.
> + *
> + * @param object The object that could not be encoded
> + * @param message The detail message
> + * @param cause The underlying cause of the exception
> + */
> public EncodeException(Object object, String message, Throwable cause) {
> super(message, cause);
> this.object = object;
> }
>
> + /**
> + * Returns the object that could not be encoded.
> + *
> + * @return The object that could not be encoded
> + */
> public Object getObject() {
> return this.object;
> }
> diff --git a/java/jakarta/websocket/Encoder.java b/java/jakarta/websocket/Encoder.java
> index 808cf3d79b..a1268268dd 100644
> --- a/java/jakarta/websocket/Encoder.java
> +++ b/java/jakarta/websocket/Encoder.java
> @@ -21,6 +21,10 @@ import java.io.OutputStream;
> import java.io.Writer;
> import java.nio.ByteBuffer;
>
> +/**
> + * Base interface for WebSocket message encoders. Encoders convert application-specific objects
> + * into WebSocket messages in text or binary form.
> + */
> public interface Encoder {
>
> /**
> @@ -32,28 +36,80 @@ public interface Encoder {
> }
>
> /**
> - * Destroy the decoder. The default implementation is a NO-OP.
> + * Destroy the encoder. The default implementation is a NO-OP.
> */
> default void destroy() {
> }
>
> + /**
> + * An encoder that encodes an object of type T into a text WebSocket message.
> + *
> + * @param <T> The type of object accepted by the encoder
> + */
> interface Text<T> extends Encoder {
>
> + /**
> + * Encodes the given object into a text string.
> + *
> + * @param object The object to encode
> + * @return The encoded text string
> + * @throws EncodeException If the object cannot be encoded
> + */
> String encode(T object) throws EncodeException;
> }
>
> + /**
> + * An encoder that encodes an object of type T into a text WebSocket message written to
> + * a {@link Writer}.
> + *
> + * @param <T> The type of object accepted by the encoder
> + */
> interface TextStream<T> extends Encoder {
>
> + /**
> + * Encodes the given object and writes the result to the writer.
> + *
> + * @param object The object to encode
> + * @param writer The writer to write the encoded data to
> + * @throws EncodeException If the object cannot be encoded
> + * @throws IOException If an I/O error occurs
> + */
> void encode(T object, Writer writer) throws EncodeException, IOException;
> }
>
> + /**
> + * An encoder that encodes an object of type T into a binary WebSocket message.
> + *
> + * @param <T> The type of object accepted by the encoder
> + */
> interface Binary<T> extends Encoder {
>
> + /**
> + * Encodes the given object into a ByteBuffer.
> + *
> + * @param object The object to encode
> + * @return The encoded binary data
> + * @throws EncodeException If the object cannot be encoded
> + */
> ByteBuffer encode(T object) throws EncodeException;
> }
>
> + /**
> + * An encoder that encodes an object of type T into a binary WebSocket message written to
> + * an {@link OutputStream}.
> + *
> + * @param <T> The type of object accepted by the encoder
> + */
> interface BinaryStream<T> extends Encoder {
>
> + /**
> + * Encodes the given object and writes the result to the output stream.
> + *
> + * @param object The object to encode
> + * @param os The output stream to write the encoded data to
> + * @throws EncodeException If the object cannot be encoded
> + * @throws IOException If an I/O error occurs
> + */
> void encode(T object, OutputStream os) throws EncodeException, IOException;
> }
> }
> diff --git a/java/jakarta/websocket/Endpoint.java b/java/jakarta/websocket/Endpoint.java
> index 059430d25e..a832ac9538 100644
> --- a/java/jakarta/websocket/Endpoint.java
> +++ b/java/jakarta/websocket/Endpoint.java
> @@ -16,8 +16,18 @@
> */
> package jakarta.websocket;
>
> +/**
> + * Base class for programmatic WebSocket endpoints. Subclasses must implement the
> + * {@link #onOpen(Session, EndpointConfig)} method to handle new connections.
> + */
> public abstract class Endpoint {
>
> + /**
> + * Creates a new Endpoint instance.
> + */
> + public Endpoint() {
> + }
> +
> /**
> * Event that is triggered when a new session starts.
> *
> diff --git a/java/jakarta/websocket/EndpointConfig.java b/java/jakarta/websocket/EndpointConfig.java
> index ed2d423610..7e85ca55c0 100644
> --- a/java/jakarta/websocket/EndpointConfig.java
> +++ b/java/jakarta/websocket/EndpointConfig.java
> @@ -19,11 +19,30 @@ package jakarta.websocket;
> import java.util.List;
> import java.util.Map;
>
> +/**
> + * Provides configuration information for a WebSocket endpoint, including encoders, decoders,
> + * and user properties.
> + */
> public interface EndpointConfig {
>
> + /**
> + * Returns the list of encoder classes for this endpoint.
> + *
> + * @return The list of encoder classes
> + */
> List<Class<? extends Encoder>> getEncoders();
>
> + /**
> + * Returns the list of decoder classes for this endpoint.
> + *
> + * @return The list of decoder classes
> + */
> List<Class<? extends Decoder>> getDecoders();
>
> + /**
> + * Returns a map of user properties associated with this endpoint configuration.
> + *
> + * @return The user properties map
> + */
> Map<String,Object> getUserProperties();
> }
> diff --git a/java/jakarta/websocket/Extension.java b/java/jakarta/websocket/Extension.java
> index a4cbca8f62..61a261c307 100644
> --- a/java/jakarta/websocket/Extension.java
> +++ b/java/jakarta/websocket/Extension.java
> @@ -18,14 +18,42 @@ package jakarta.websocket;
>
> import java.util.List;
>
> +/**
> + * Represents a WebSocket extension that can be negotiated during the handshake.
> + */
> public interface Extension {
> +
> + /**
> + * Returns the name of this extension.
> + *
> + * @return The extension name
> + */
> String getName();
>
> + /**
> + * Returns the parameters associated with this extension.
> + *
> + * @return The list of extension parameters
> + */
> List<Parameter> getParameters();
>
> + /**
> + * Represents a parameter of a WebSocket extension.
> + */
> interface Parameter {
> +
> + /**
> + * Returns the name of this parameter.
> + *
> + * @return The parameter name
> + */
> String getName();
>
> + /**
> + * Returns the value of this parameter.
> + *
> + * @return The parameter value
> + */
> String getValue();
> }
> }
> diff --git a/java/jakarta/websocket/HandshakeResponse.java b/java/jakarta/websocket/HandshakeResponse.java
> index e5faf9d801..900551f880 100644
> --- a/java/jakarta/websocket/HandshakeResponse.java
> +++ b/java/jakarta/websocket/HandshakeResponse.java
> @@ -19,6 +19,9 @@ package jakarta.websocket;
> import java.util.List;
> import java.util.Map;
>
> +/**
> + * Represents the HTTP response returned by the server during a WebSocket handshake.
> + */
> public interface HandshakeResponse {
>
> /**
> @@ -26,5 +29,10 @@ public interface HandshakeResponse {
> */
> String SEC_WEBSOCKET_ACCEPT = "Sec-WebSocket-Accept";
>
> + /**
> + * Returns the HTTP headers from the handshake response.
> + *
> + * @return The HTTP headers
> + */
> Map<String,List<String>> getHeaders();
> }
> diff --git a/java/jakarta/websocket/MessageHandler.java b/java/jakarta/websocket/MessageHandler.java
> index 748dd76776..ace7c96702 100644
> --- a/java/jakarta/websocket/MessageHandler.java
> +++ b/java/jakarta/websocket/MessageHandler.java
> @@ -16,8 +16,18 @@
> */
> package jakarta.websocket;
>
> +/**
> + * Base interface for WebSocket message handlers. Use {@link Whole} for handling complete
> + * messages and {@link Partial} for handling messages that may arrive in fragments.
> + */
> public interface MessageHandler {
>
> + /**
> + * A message handler that receives partial (fragmented) messages. The handler is called
> + * multiple times for a single WebSocket message if it arrives in fragments.
> + *
> + * @param <T> The type of message data
> + */
> interface Partial<T> extends MessageHandler {
>
> /**
> @@ -29,6 +39,12 @@ public interface MessageHandler {
> void onMessage(T messagePart, boolean last);
> }
>
> + /**
> + * A message handler that receives whole (complete) messages. The handler is called once
> + * per WebSocket message.
> + *
> + * @param <T> The type of message data
> + */
> interface Whole<T> extends MessageHandler {
>
> /**
> diff --git a/java/jakarta/websocket/OnClose.java b/java/jakarta/websocket/OnClose.java
> index 31291165bc..8c071d1f85 100644
> --- a/java/jakarta/websocket/OnClose.java
> +++ b/java/jakarta/websocket/OnClose.java
> @@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle the close event. The annotated method
> + * will be called when the WebSocket session is closed.
> + */
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.METHOD)
> public @interface OnClose {
> diff --git a/java/jakarta/websocket/OnError.java b/java/jakarta/websocket/OnError.java
> index a09a5bde28..cba6abd9ac 100644
> --- a/java/jakarta/websocket/OnError.java
> +++ b/java/jakarta/websocket/OnError.java
> @@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle error events. The annotated method
> + * will be called when an error occurs on the WebSocket session.
> + */
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.METHOD)
> public @interface OnError {
> diff --git a/java/jakarta/websocket/OnMessage.java b/java/jakarta/websocket/OnMessage.java
> index 34cfcfa18e..49d95b8c74 100644
> --- a/java/jakarta/websocket/OnMessage.java
> +++ b/java/jakarta/websocket/OnMessage.java
> @@ -21,8 +21,19 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle incoming WebSocket messages. The annotated
> + * method will be called when a message is received.
> + */
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.METHOD)
> public @interface OnMessage {
> +
> + /**
> + * The maximum message size in bytes that this handler will accept. Messages larger than
> + * this size will be discarded. A value of -1 indicates no limit.
> + *
> + * @return The maximum message size in bytes
> + */
> long maxMessageSize() default -1;
> }
> diff --git a/java/jakarta/websocket/OnOpen.java b/java/jakarta/websocket/OnOpen.java
> index 26b8e9d1e0..48f98d7bbd 100644
> --- a/java/jakarta/websocket/OnOpen.java
> +++ b/java/jakarta/websocket/OnOpen.java
> @@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle the open event. The annotated method
> + * will be called when a new WebSocket session is established.
> + */
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.METHOD)
> public @interface OnOpen {
> diff --git a/java/jakarta/websocket/RemoteEndpoint.java b/java/jakarta/websocket/RemoteEndpoint.java
> index 9826d98cc0..a485581c65 100644
> --- a/java/jakarta/websocket/RemoteEndpoint.java
> +++ b/java/jakarta/websocket/RemoteEndpoint.java
> @@ -23,8 +23,15 @@ import java.nio.ByteBuffer;
> import java.util.concurrent.Future;
>
>
> +/**
> + * Interface for sending messages to the remote endpoint of a WebSocket session.
> + * Provides both synchronous ({@link Basic}) and asynchronous ({@link Async}) sending capabilities.
> + */
> public interface RemoteEndpoint {
>
> + /**
> + * Asynchronous API for sending messages to the remote endpoint.
> + */
> interface Async extends RemoteEndpoint {
>
> /**
> @@ -109,6 +116,9 @@ public interface RemoteEndpoint {
>
> }
>
> + /**
> + * Synchronous (blocking) API for sending messages to the remote endpoint.
> + */
> interface Basic extends RemoteEndpoint {
>
> /**
> @@ -155,8 +165,20 @@ public interface RemoteEndpoint {
> */
> void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException;
>
> + /**
> + * Returns an {@link OutputStream} for sending a binary message to the remote endpoint.
> + *
> + * @return An output stream for sending binary data
> + * @throws IOException if an I/O error occurs
> + */
> OutputStream getSendStream() throws IOException;
>
> + /**
> + * Returns a {@link Writer} for sending a text message to the remote endpoint.
> + *
> + * @return A writer for sending text data
> + * @throws IOException if an I/O error occurs
> + */
> Writer getSendWriter() throws IOException;
>
> /**
> diff --git a/java/jakarta/websocket/SendHandler.java b/java/jakarta/websocket/SendHandler.java
> index 9e8317c5b5..ee34f7a25c 100644
> --- a/java/jakarta/websocket/SendHandler.java
> +++ b/java/jakarta/websocket/SendHandler.java
> @@ -16,7 +16,15 @@
> */
> package jakarta.websocket;
>
> +/**
> + * Callback interface for handling the result of an asynchronous WebSocket message send operation.
> + */
> public interface SendHandler {
>
> + /**
> + * Called when the asynchronous send operation completes.
> + *
> + * @param result The result of the send operation
> + */
> void onResult(SendResult result);
> }
> diff --git a/java/jakarta/websocket/SendResult.java b/java/jakarta/websocket/SendResult.java
> index f506c881af..b7a6842f37 100644
> --- a/java/jakarta/websocket/SendResult.java
> +++ b/java/jakarta/websocket/SendResult.java
> @@ -16,6 +16,9 @@
> */
> package jakarta.websocket;
>
> +/**
> + * Represents the result of an asynchronous WebSocket message send operation.
> + */
> public final class SendResult {
> private final Session session;
> private final Throwable exception;
> @@ -66,10 +69,21 @@ public final class SendResult {
> this(null, null);
> }
>
> + /**
> + * Returns the exception that occurred during the send operation, or {@code null} if the
> + * operation was successful.
> + *
> + * @return The exception, or {@code null} if successful
> + */
> public Throwable getException() {
> return exception;
> }
>
> + /**
> + * Returns whether the send operation was successful.
> + *
> + * @return {@code true} if the send was successful, {@code false} otherwise
> + */
> public boolean isOK() {
> return ok;
> }
> diff --git a/java/jakarta/websocket/Session.java b/java/jakarta/websocket/Session.java
> index 21e20ea086..eb439795a4 100644
> --- a/java/jakarta/websocket/Session.java
> +++ b/java/jakarta/websocket/Session.java
> @@ -24,6 +24,11 @@ import java.util.List;
> import java.util.Map;
> import java.util.Set;
>
> +/**
> + * Represents a WebSocket session, which is the WebSocket connection between a client and a server.
> + * A session is created when a WebSocket connection is established and is used to send and receive
> + * messages.
> + */
> public interface Session extends Closeable {
>
> /**
> @@ -46,18 +51,54 @@ public interface Session extends Closeable {
> */
> void addMessageHandler(MessageHandler handler) throws IllegalStateException;
>
> + /**
> + * Returns the set of message handlers currently registered on this session.
> + *
> + * @return The set of registered message handlers
> + */
> Set<MessageHandler> getMessageHandlers();
>
> + /**
> + * Removes the specified message handler from this session.
> + *
> + * @param listener The message handler to remove
> + */
> void removeMessageHandler(MessageHandler listener);
>
> + /**
> + * Returns the version of the WebSocket protocol in use for this session.
> + *
> + * @return The protocol version
> + */
> String getProtocolVersion();
>
> + /**
> + * Returns the sub-protocol negotiated for this session, or {@code null} if no sub-protocol
> + * was negotiated.
> + *
> + * @return The negotiated sub-protocol
> + */
> String getNegotiatedSubprotocol();
>
> + /**
> + * Returns the list of extensions negotiated for this session.
> + *
> + * @return The list of negotiated extensions
> + */
> List<Extension> getNegotiatedExtensions();
>
> + /**
> + * Returns whether this session is using a secure connection (wss://).
> + *
> + * @return {@code true} if the connection is secure
> + */
> boolean isSecure();
>
> + /**
> + * Returns whether this session is currently open.
> + *
> + * @return {@code true} if the session is open
> + */
> boolean isOpen();
>
> /**
> @@ -104,8 +145,19 @@ public interface Session extends Closeable {
> */
> int getMaxTextMessageBufferSize();
>
> + /**
> + * Returns the asynchronous remote endpoint for this session, used for non-blocking message
> + * sending.
> + *
> + * @return The asynchronous remote endpoint
> + */
> RemoteEndpoint.Async getAsyncRemote();
>
> + /**
> + * Returns the synchronous remote endpoint for this session, used for blocking message sending.
> + *
> + * @return The synchronous remote endpoint
> + */
> RemoteEndpoint.Basic getBasicRemote();
>
> /**
> @@ -135,16 +187,47 @@ public interface Session extends Closeable {
> */
> void close(CloseReason closeReason) throws IOException;
>
> + /**
> + * Returns the URI of the request that initiated this WebSocket session.
> + *
> + * @return The request URI
> + */
> URI getRequestURI();
>
> + /**
> + * Returns the query parameters from the request that initiated this WebSocket session.
> + *
> + * @return The query parameter map
> + */
> Map<String,List<String>> getRequestParameterMap();
>
> + /**
> + * Returns the query string from the request that initiated this WebSocket session.
> + *
> + * @return The query string
> + */
> String getQueryString();
>
> + /**
> + * Returns the path parameters extracted from the request URI using the endpoint's URI template.
> + *
> + * @return The path parameter map
> + */
> Map<String,String> getPathParameters();
>
> + /**
> + * Returns a map of user properties associated with this session.
> + *
> + * @return The user properties map
> + */
> Map<String,Object> getUserProperties();
>
> + /**
> + * Returns the principal of the user associated with this session, or {@code null} if the
> + * user is not authenticated.
> + *
> + * @return The user principal
> + */
> Principal getUserPrincipal();
>
> /**
> diff --git a/java/jakarta/websocket/SessionException.java b/java/jakarta/websocket/SessionException.java
> index d1d0f9908c..7645c73fa0 100644
> --- a/java/jakarta/websocket/SessionException.java
> +++ b/java/jakarta/websocket/SessionException.java
> @@ -18,20 +18,38 @@ package jakarta.websocket;
>
> import java.io.Serial;
>
> +/**
> + * Exception thrown when an error occurs on a WebSocket session.
> + */
> public class SessionException extends Exception {
>
> @Serial
> private static final long serialVersionUID = 1L;
>
> + /**
> + * The session on which the error occurred.
> + */
> private final Session session;
>
>
> + /**
> + * Creates a SessionException with the specified detail message, cause, and session.
> + *
> + * @param message The detail message
> + * @param cause The underlying cause of the exception
> + * @param session The session on which the error occurred
> + */
> public SessionException(String message, Throwable cause, Session session) {
> super(message, cause);
> this.session = session;
> }
>
>
> + /**
> + * Returns the session on which the error occurred.
> + *
> + * @return The session
> + */
> public Session getSession() {
> return session;
> }
> diff --git a/java/jakarta/websocket/WebSocketContainer.java b/java/jakarta/websocket/WebSocketContainer.java
> index 82ddb7ff47..7613ece7a7 100644
> --- a/java/jakarta/websocket/WebSocketContainer.java
> +++ b/java/jakarta/websocket/WebSocketContainer.java
> @@ -20,6 +20,9 @@ import java.io.IOException;
> import java.net.URI;
> import java.util.Set;
>
> +/**
> + * Provides the ability to create new WebSocket client connections.
> + */
> public interface WebSocketContainer {
>
> /**
> @@ -36,8 +39,27 @@ public interface WebSocketContainer {
> */
> void setAsyncSendTimeout(long timeout);
>
> + /**
> + * Creates a new connection to the WebSocket server endpoint.
> + *
> + * @param endpoint The POJO endpoint instance that will handle responses from the server
> + * @param path The full URL of the WebSocket endpoint to connect to
> + * @return The WebSocket session for the connection
> + * @throws DeploymentException If the connection cannot be established
> + * @throws IOException If an I/O error occurred while trying to establish the connection
> + */
> Session connectToServer(Object endpoint, URI path) throws DeploymentException, IOException;
>
> + /**
> + * Creates a new connection to the WebSocket server endpoint.
> + *
> + * @param annotatedEndpointClass The annotated endpoint class. An instance of this class will be
> + * created to handle responses from the server
> + * @param path The full URL of the WebSocket endpoint to connect to
> + * @return The WebSocket session for the connection
> + * @throws DeploymentException If the connection cannot be established
> + * @throws IOException If an I/O error occurred while trying to establish the connection
> + */
> Session connectToServer(Class<?> annotatedEndpointClass, URI path) throws DeploymentException, IOException;
>
> /**
> diff --git a/java/jakarta/websocket/server/HandshakeRequest.java b/java/jakarta/websocket/server/HandshakeRequest.java
> index 457942ed76..a17cb21545 100644
> --- a/java/jakarta/websocket/server/HandshakeRequest.java
> +++ b/java/jakarta/websocket/server/HandshakeRequest.java
> @@ -26,17 +26,51 @@ import java.util.Map;
> */
> public interface HandshakeRequest {
>
> + /**
> + * Name of the Sec-WebSocket-Key HTTP header.
> + */
> String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key";
> + /**
> + * Name of the Sec-WebSocket-Protocol HTTP header.
> + */
> String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol";
> + /**
> + * Name of the Sec-WebSocket-Version HTTP header.
> + */
> String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version";
> + /**
> + * Name of the Sec-WebSocket-Extensions HTTP header.
> + */
> String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions";
>
> + /**
> + * Returns the HTTP headers from the handshake request.
> + *
> + * @return The HTTP headers
> + */
> Map<String,List<String>> getHeaders();
>
> + /**
> + * Returns the principal of the user associated with this request, or {@code null} if the
> + * user is not authenticated.
> + *
> + * @return The user principal
> + */
> Principal getUserPrincipal();
>
> + /**
> + * Returns the URI of the handshake request.
> + *
> + * @return The request URI
> + */
> URI getRequestURI();
>
> + /**
> + * Returns whether the user associated with this request is in the given role.
> + *
> + * @param role The role to check
> + * @return {@code true} if the user is in the specified role
> + */
> boolean isUserInRole(String role);
>
> /**
> @@ -47,7 +81,17 @@ public interface HandshakeRequest {
> */
> Object getHttpSession();
>
> + /**
> + * Returns the query parameters from the handshake request.
> + *
> + * @return The query parameter map
> + */
> Map<String,List<String>> getParameterMap();
>
> + /**
> + * Returns the query string from the handshake request.
> + *
> + * @return The query string
> + */
> String getQueryString();
> }
> diff --git a/java/jakarta/websocket/server/PathParam.java b/java/jakarta/websocket/server/PathParam.java
> index 22293b3dda..b86dbbf85b 100644
> --- a/java/jakarta/websocket/server/PathParam.java
> +++ b/java/jakarta/websocket/server/PathParam.java
> @@ -28,5 +28,11 @@ import java.lang.annotation.Target;
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.PARAMETER)
> public @interface PathParam {
> +
> + /**
> + * The name of the path parameter from the URI template.
> + *
> + * @return The path parameter name
> + */
> String value();
> }
> diff --git a/java/jakarta/websocket/server/ServerContainer.java b/java/jakarta/websocket/server/ServerContainer.java
> index 82b92dc7bd..e6c4f68c91 100644
> --- a/java/jakarta/websocket/server/ServerContainer.java
> +++ b/java/jakarta/websocket/server/ServerContainer.java
> @@ -26,8 +26,21 @@ import jakarta.websocket.WebSocketContainer;
> * Provides the ability to deploy endpoints programmatically.
> */
> public interface ServerContainer extends WebSocketContainer {
> + /**
> + * Deploys the given endpoint class. The class must be annotated with
> + * {@link jakarta.websocket.server.ServerEndpoint} or extend {@link jakarta.websocket.Endpoint}.
> + *
> + * @param clazz The endpoint class to deploy
> + * @throws DeploymentException If the endpoint cannot be deployed
> + */
> void addEndpoint(Class<?> clazz) throws DeploymentException;
>
> + /**
> + * Deploys the endpoint configured by the given {@link ServerEndpointConfig}.
> + *
> + * @param sec The server endpoint configuration
> + * @throws DeploymentException If the endpoint cannot be deployed
> + */
> void addEndpoint(ServerEndpointConfig sec) throws DeploymentException;
>
> /**
> diff --git a/java/jakarta/websocket/server/ServerEndpoint.java b/java/jakarta/websocket/server/ServerEndpoint.java
> index b29ebec134..f0efc31112 100644
> --- a/java/jakarta/websocket/server/ServerEndpoint.java
> +++ b/java/jakarta/websocket/server/ServerEndpoint.java
> @@ -24,6 +24,11 @@ import java.lang.annotation.Target;
> import jakarta.websocket.Decoder;
> import jakarta.websocket.Encoder;
>
> +/**
> + * Annotates a class as a WebSocket server endpoint. The annotation provides configuration
> + * information about the endpoint such as the URI path, subprotocols, encoders, decoders,
> + * and configurator.
> + */
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.TYPE)
> public @interface ServerEndpoint {
> @@ -35,11 +40,31 @@ public @interface ServerEndpoint {
> */
> String value();
>
> + /**
> + * The sub-protocols that this server endpoint supports.
> + *
> + * @return The list of supported sub-protocols
> + */
> String[] subprotocols() default {};
>
> + /**
> + * The decoder classes that this server endpoint uses.
> + *
> + * @return The list of decoder classes
> + */
> Class<? extends Decoder>[] decoders() default {};
>
> + /**
> + * The encoder classes that this server endpoint uses.
> + *
> + * @return The list of encoder classes
> + */
> Class<? extends Encoder>[] encoders() default {};
>
> + /**
> + * The configurator class used to customize the WebSocket handshake.
> + *
> + * @return The configurator class
> + */
> Class<? extends ServerEndpointConfig.Configurator> configurator() default ServerEndpointConfig.Configurator.class;
> }
> diff --git a/java/jakarta/websocket/server/ServerEndpointConfig.java b/java/jakarta/websocket/server/ServerEndpointConfig.java
> index e72a879608..caf697a61b 100644
> --- a/java/jakarta/websocket/server/ServerEndpointConfig.java
> +++ b/java/jakarta/websocket/server/ServerEndpointConfig.java
> @@ -33,6 +33,11 @@ import jakarta.websocket.HandshakeResponse;
> */
> public interface ServerEndpointConfig extends EndpointConfig {
>
> + /**
> + * Returns the class of the endpoint.
> + *
> + * @return The endpoint class
> + */
> Class<?> getEndpointClass();
>
> /**
> @@ -43,15 +48,40 @@ public interface ServerEndpointConfig extends EndpointConfig {
> */
> String getPath();
>
> + /**
> + * Returns the list of sub-protocols supported by this endpoint.
> + *
> + * @return The list of supported sub-protocols
> + */
> List<String> getSubprotocols();
>
> + /**
> + * Returns the list of extensions supported by this endpoint.
> + *
> + * @return The list of supported extensions
> + */
> List<Extension> getExtensions();
>
> + /**
> + * Returns the configurator for this server endpoint.
> + *
> + * @return The configurator
> + */
> Configurator getConfigurator();
>
>
> + /**
> + * Builder for creating {@link ServerEndpointConfig} instances.
> + */
> final class Builder {
>
> + /**
> + * Creates a new builder for the given endpoint class and path.
> + *
> + * @param endpointClass The endpoint class
> + * @param path The path at which the endpoint will be registered
> + * @return A new builder instance
> + */
> public static Builder create(Class<?> endpointClass, String path) {
> return new Builder(endpointClass, path);
> }
> @@ -83,12 +113,23 @@ public interface ServerEndpointConfig extends EndpointConfig {
> this.path = path;
> }
>
> + /**
> + * Builds and returns a {@link ServerEndpointConfig} with the configured settings.
> + *
> + * @return The configured server endpoint configuration
> + */
> public ServerEndpointConfig build() {
> return new DefaultServerEndpointConfig(endpointClass, path, subprotocols, extensions, encoders, decoders,
> configurator);
> }
>
>
> + /**
> + * Sets the list of encoder classes to use for the WebSocket connection.
> + *
> + * @param encoders The list of encoder classes
> + * @return This builder instance
> + */
> public Builder encoders(List<Class<? extends Encoder>> encoders) {
> if (encoders == null || encoders.isEmpty()) {
> this.encoders = Collections.emptyList();
> @@ -99,6 +140,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the list of decoder classes to use for the WebSocket connection.
> + *
> + * @param decoders The list of decoder classes
> + * @return This builder instance
> + */
> public Builder decoders(List<Class<? extends Decoder>> decoders) {
> if (decoders == null || decoders.isEmpty()) {
> this.decoders = Collections.emptyList();
> @@ -109,6 +156,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the list of sub-protocols supported by the endpoint.
> + *
> + * @param subprotocols The list of sub-protocols
> + * @return This builder instance
> + */
> public Builder subprotocols(List<String> subprotocols) {
> if (subprotocols == null || subprotocols.isEmpty()) {
> this.subprotocols = Collections.emptyList();
> @@ -119,6 +172,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the list of extensions supported by the endpoint.
> + *
> + * @param extensions The list of extensions
> + * @return This builder instance
> + */
> public Builder extensions(List<Extension> extensions) {
> if (extensions == null || extensions.isEmpty()) {
> this.extensions = Collections.emptyList();
> @@ -129,6 +188,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Sets the configurator to use for the WebSocket handshake.
> + *
> + * @param serverEndpointConfigurator The configurator, or {@code null} to use the default
> + * @return This builder instance
> + */
> public Builder configurator(Configurator serverEndpointConfigurator) {
> if (serverEndpointConfigurator == null) {
> this.configurator = Configurator.fetchContainerDefaultConfigurator();
> @@ -140,8 +205,18 @@ public interface ServerEndpointConfig extends EndpointConfig {
> }
>
>
> + /**
> + * Provides a mechanism to customize the WebSocket handshake for server endpoints.
> + * Applications may subclass this to inspect or modify the handshake.
> + */
> class Configurator {
>
> + /**
> + * Creates a new instance of the Configurator.
> + */
> + public Configurator() {
> + }
> +
> private static volatile Configurator defaultImpl = null;
> private static final Object defaultImplLock = new Object();
>
> @@ -195,22 +270,61 @@ public interface ServerEndpointConfig extends EndpointConfig {
> return fetchContainerDefaultConfigurator();
> }
>
> + /**
> + * Determines the sub-protocol to use for the WebSocket connection by comparing the
> + * supported and requested sub-protocols.
> + *
> + * @param supported The list of sub-protocols supported by the endpoint
> + * @param requested The list of sub-protocols requested by the client
> + * @return The negotiated sub-protocol, or {@code null} if none matches
> + */
> public String getNegotiatedSubprotocol(List<String> supported, List<String> requested) {
> return fetchContainerDefaultConfigurator().getNegotiatedSubprotocol(supported, requested);
> }
>
> + /**
> + * Determines the extensions to use for the WebSocket connection by comparing the
> + * installed and requested extensions.
> + *
> + * @param installed The list of extensions installed on the server
> + * @param requested The list of extensions requested by the client
> + * @return The list of negotiated extensions
> + */
> public List<Extension> getNegotiatedExtensions(List<Extension> installed, List<Extension> requested) {
> return fetchContainerDefaultConfigurator().getNegotiatedExtensions(installed, requested);
> }
>
> + /**
> + * Checks whether the given Origin header value is acceptable. The default implementation
> + * always returns {@code true}.
> + *
> + * @param originHeaderValue The Origin header value to check
> + * @return {@code true} if the origin is acceptable
> + */
> public boolean checkOrigin(String originHeaderValue) {
> return fetchContainerDefaultConfigurator().checkOrigin(originHeaderValue);
> }
>
> + /**
> + * Provides the opportunity to modify the handshake before it is completed. This method
> + * is called after the sub-protocol and extensions have been negotiated.
> + *
> + * @param sec The server endpoint configuration
> + * @param request The handshake request
> + * @param response The handshake response
> + */
> public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) {
> fetchContainerDefaultConfigurator().modifyHandshake(sec, request, response);
> }
>
> + /**
> + * Creates a new instance of the endpoint class.
> + *
> + * @param <T> The type of the endpoint class
> + * @param clazz The endpoint class
> + * @return A new instance of the endpoint
> + * @throws InstantiationException If the endpoint cannot be instantiated
> + */
> public <T extends Object> T getEndpointInstance(Class<T> clazz) throws InstantiationException {
> return fetchContainerDefaultConfigurator().getEndpointInstance(clazz);
> }
> diff --git a/java/jakarta/xml/ws/WebServiceRef.java b/java/jakarta/xml/ws/WebServiceRef.java
> index 3c7e7a4738..e90a6f9c3c 100644
> --- a/java/jakarta/xml/ws/WebServiceRef.java
> +++ b/java/jakarta/xml/ws/WebServiceRef.java
> @@ -21,19 +21,48 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Declares a reference to a web service. The WebServiceRef annotation can be applied to a field or method to inject
> + * a reference to a web service, or to a class to declare web service dependencies.
> + */
> @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface WebServiceRef {
> +
> + /**
> + * The name for the web service reference. The name is relative to the default initial context.
> + *
> + * @return the name of the web service reference
> + */
> String name() default "";
>
> + /**
> + * The type of the injected object, typically the service endpoint interface.
> + *
> + * @return the type class
> + */
> @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
> Class type() default Object.class;
>
> + /**
> + * The web service class, typically the service endpoint interface class.
> + *
> + * @return the web service class
> + */
> @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
> Class value() default Object.class;
>
> + /**
> + * The location of the WSDL document for the web service.
> + *
> + * @return the WSDL location
> + */
> String wsdlLocation() default "";
>
> + /**
> + * A provider-specific name that this reference should be mapped to.
> + *
> + * @return the provider-specific mapped name
> + */
> String mappedName() default "";
> }
> diff --git a/java/jakarta/xml/ws/WebServiceRefs.java b/java/jakarta/xml/ws/WebServiceRefs.java
> index 0b69d9e1f2..020d86a674 100644
> --- a/java/jakarta/xml/ws/WebServiceRefs.java
> +++ b/java/jakarta/xml/ws/WebServiceRefs.java
> @@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
> import java.lang.annotation.RetentionPolicy;
> import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple {@link WebServiceRef} annotations on a single declaration. Use this annotation when a class has
> + * dependencies on more than one web service.
> + */
> @Target(ElementType.TYPE)
> @Retention(RetentionPolicy.RUNTIME)
> -
> public @interface WebServiceRefs {
> +
> + /**
> + * The array of WebServiceRef annotations.
> + *
> + * @return the WebServiceRef annotations
> + */
> WebServiceRef[] value();
> }
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: dev-help@tomcat.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org