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/09/10 21:26:32 UTC
(tomcat) branch main updated: Documentation updates from code review
This is an automated email from the ASF dual-hosted git repository.
rmaucher pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new 05b5d70555 Documentation updates from code review
05b5d70555 is described below
commit 05b5d70555068a6647226e9924b2d7f1b9978b03
Author: remm <re...@apache.org>
AuthorDate: Thu Sep 10 23:26:19 2026 +0200
Documentation updates from code review
Javadoc fixes.
Better explanations.
Typos.
Co authored with OpenCode.
---
java/org/apache/catalina/Container.java | 8 ++---
java/org/apache/catalina/Context.java | 14 ++++-----
java/org/apache/catalina/DistributedManager.java | 4 +--
java/org/apache/catalina/Engine.java | 2 +-
java/org/apache/catalina/Host.java | 6 ++--
java/org/apache/catalina/Lifecycle.java | 6 ++--
java/org/apache/catalina/Manager.java | 6 ++--
java/org/apache/catalina/Server.java | 6 ++--
java/org/apache/catalina/Store.java | 14 ++++-----
java/org/apache/catalina/User.java | 8 +++--
java/org/apache/catalina/UserDatabase.java | 2 +-
java/org/apache/catalina/WebResourceLockSet.java | 4 +--
java/org/apache/catalina/WebResourceRoot.java | 6 ++--
java/org/apache/catalina/Wrapper.java | 4 +--
.../apache/catalina/ant/AbstractCatalinaTask.java | 9 +++---
.../catalina/ant/BaseRedirectorHelperTask.java | 2 +-
.../apache/catalina/ant/JKStatusUpdateTask.java | 4 +--
java/org/apache/catalina/ant/SessionsTask.java | 9 +++---
java/org/apache/catalina/ant/ValidatorTask.java | 1 -
.../catalina/ant/jmx/JMXAccessorCreateTask.java | 2 +-
.../catalina/ant/jmx/JMXAccessorGetTask.java | 5 ++-
.../catalina/ant/jmx/JMXAccessorInvokeTask.java | 2 +-
.../catalina/ant/jmx/JMXAccessorQueryTask.java | 6 ++--
.../catalina/ant/jmx/JMXAccessorSetTask.java | 11 +++----
.../apache/catalina/ant/jmx/JMXAccessorTask.java | 9 +++---
.../ant/jmx/JMXAccessorUnregisterTask.java | 7 +++--
.../catalina/authenticator/AuthenticatorBase.java | 2 +-
.../catalina/authenticator/BasicAuthenticator.java | 13 ++++----
.../authenticator/DigestAuthenticator.java | 10 +++---
.../authenticator/SingleSignOnSessionKey.java | 3 --
.../authenticator/SpnegoAuthenticator.java | 4 +--
.../authenticator/jaspic/CallbackHandlerImpl.java | 3 +-
.../jaspic/SimpleServerAuthConfig.java | 2 +-
java/org/apache/catalina/connector/Connector.java | 2 +-
.../catalina/connector/CoyoteOutputStream.java | 3 +-
.../org/apache/catalina/connector/InputBuffer.java | 4 +--
java/org/apache/catalina/connector/Request.java | 6 ++--
.../apache/catalina/connector/RequestFacade.java | 2 +-
.../apache/catalina/connector/ResponseFacade.java | 2 +-
.../org/apache/catalina/core/AccessLogAdapter.java | 7 +++++
.../catalina/core/ApplicationHttpRequest.java | 7 ++---
.../catalina/core/ApplicationHttpResponse.java | 7 ++---
java/org/apache/catalina/core/ApplicationPart.java | 5 +--
.../core/ApplicationSessionCookieConfig.java | 2 ++
.../apache/catalina/core/AprLifecycleListener.java | 3 +-
.../org/apache/catalina/core/AsyncContextImpl.java | 2 +-
.../apache/catalina/core/JniLifecycleListener.java | 2 +-
java/org/apache/catalina/core/StandardContext.java | 2 +-
java/org/apache/catalina/core/StandardHost.java | 2 +-
.../org/apache/catalina/core/StandardPipeline.java | 5 ++-
java/org/apache/catalina/core/StandardServer.java | 2 +-
java/org/apache/catalina/core/StandardWrapper.java | 8 ++---
.../apache/catalina/core/StandardWrapperValve.java | 2 --
.../apache/catalina/core/mbeans-descriptors.xml | 36 +++++++++++-----------
.../catalina/deploy/NamingResourcesImpl.java | 9 +++---
.../catalina/filters/AddDefaultCharsetFilter.java | 2 +-
java/org/apache/catalina/filters/CorsFilter.java | 6 ++--
.../catalina/filters/CsrfPreventionFilter.java | 7 +++--
.../apache/catalina/filters/RemoteIpFilter.java | 26 ++++++++--------
.../org/apache/catalina/filters/RequestFilter.java | 3 +-
java/org/apache/catalina/ha/CatalinaCluster.java | 2 +-
java/org/apache/catalina/ha/ClusterDeployer.java | 11 ++-----
java/org/apache/catalina/ha/ClusterManager.java | 8 ++---
.../ha/authenticator/ClusterSingleSignOn.java | 3 +-
.../catalina/ha/backend/HeartbeatListener.java | 9 +++---
.../catalina/ha/context/ReplicatedContext.java | 3 +-
.../apache/catalina/ha/deploy/FarmWarDeployer.java | 5 ++-
.../catalina/ha/deploy/FileMessageFactory.java | 2 +-
java/org/apache/catalina/ha/deploy/WarWatcher.java | 2 +-
.../apache/catalina/ha/session/DeltaManager.java | 3 +-
.../apache/catalina/ha/session/DeltaRequest.java | 3 +-
.../catalina/ha/session/JvmRouteBinderValve.java | 2 +-
.../catalina/ha/session/SessionMessageImpl.java | 2 +-
.../apache/catalina/ha/tcp/ReplicationValve.java | 2 +-
.../apache/catalina/ha/tcp/SimpleTcpCluster.java | 2 +-
.../apache/catalina/ha/tcp/mbeans-descriptors.xml | 4 +--
.../catalina/loader/WebappClassLoaderBase.java | 11 +++----
.../catalina/manager/HTMLManagerServlet.java | 2 +-
java/org/apache/catalina/manager/JspHelper.java | 2 +-
.../apache/catalina/manager/ManagerServlet.java | 24 +++++++++++++--
.../catalina/manager/StatusManagerServlet.java | 4 ++-
.../manager/host/HTMLHostManagerServlet.java | 3 +-
.../catalina/manager/host/HostManagerServlet.java | 7 +++--
.../apache/catalina/manager/util/SessionUtils.java | 12 +++++---
java/org/apache/catalina/mapper/Mapper.java | 2 +-
.../org/apache/catalina/mapper/MapperListener.java | 2 +-
.../mbeans/GlobalResourcesLifecycleListener.java | 5 ++-
java/org/apache/catalina/mbeans/MBeanDumper.java | 4 +--
java/org/apache/catalina/mbeans/MBeanFactory.java | 1 -
.../org/apache/catalina/realm/DataSourceRealm.java | 6 ++--
.../catalina/realm/JAASMemoryLoginModule.java | 6 ++--
java/org/apache/catalina/realm/JNDIRealm.java | 17 +++++-----
java/org/apache/catalina/realm/LockOutRealm.java | 4 +--
.../realm/MessageDigestCredentialHandler.java | 11 ++++---
java/org/apache/catalina/realm/RealmBase.java | 16 +++++-----
.../catalina/security/LocalStrings.properties | 6 ++--
.../apache/catalina/security/SecurityListener.java | 5 +--
.../apache/catalina/servlets/WebdavServlet.java | 3 +-
java/org/apache/catalina/session/FileStore.java | 2 +-
java/org/apache/catalina/session/ManagerBase.java | 3 +-
.../catalina/session/PersistentManagerBase.java | 24 ++++++++-------
java/org/apache/catalina/session/StoreBase.java | 8 +++--
.../catalina/ssi/ByteArrayServletOutputStream.java | 3 +-
.../catalina/ssi/ResponseIncludeWrapper.java | 4 +--
.../apache/catalina/ssi/SSIExternalResolver.java | 5 +--
java/org/apache/catalina/ssi/SSIServlet.java | 4 +--
.../apache/catalina/ssi/SSIServletRequestUtil.java | 7 +++--
java/org/apache/catalina/ssi/SSISet.java | 3 +-
.../catalina/ssi/SSIStopProcessingException.java | 5 +--
java/org/apache/catalina/startup/Catalina.java | 4 +--
.../catalina/startup/CatalinaProperties.java | 1 -
.../org/apache/catalina/startup/ContextConfig.java | 2 +-
.../catalina/startup/CredentialHandlerRuleSet.java | 5 +++
java/org/apache/catalina/startup/ExpandWar.java | 8 +++--
java/org/apache/catalina/startup/HostConfig.java | 3 --
java/org/apache/catalina/startup/Tomcat.java | 9 +++---
java/org/apache/catalina/startup/Tool.java | 2 +-
java/org/apache/catalina/startup/UserConfig.java | 2 +-
.../apache/catalina/startup/WebAnnotationSet.java | 2 +-
.../catalina/storeconfig/CatalinaClusterSF.java | 4 +--
.../storeconfig/ConnectorStoreAppender.java | 3 +-
.../apache/catalina/storeconfig/IStoreConfig.java | 4 +--
.../apache/catalina/storeconfig/IStoreFactory.java | 4 +--
.../apache/catalina/storeconfig/JarScannerSF.java | 2 +-
.../catalina/storeconfig/NamingResourcesSF.java | 2 +-
.../catalina/storeconfig/StandardContextSF.java | 6 ++--
.../catalina/storeconfig/StoreDescription.java | 8 +++--
.../catalina/storeconfig/StoreFactoryBase.java | 4 +--
.../apache/catalina/storeconfig/StoreLoader.java | 10 ++----
java/org/apache/catalina/tribes/Channel.java | 5 +--
.../apache/catalina/tribes/ChannelListener.java | 2 +-
.../org/apache/catalina/tribes/ChannelMessage.java | 4 +--
.../org/apache/catalina/tribes/ManagedChannel.java | 2 +-
java/org/apache/catalina/tribes/Member.java | 4 +--
.../apache/catalina/tribes/MembershipService.java | 4 +--
java/org/apache/catalina/tribes/UniqueId.java | 2 +-
.../catalina/tribes/group/ChannelCoordinator.java | 2 ++
.../apache/catalina/tribes/group/RpcChannel.java | 5 +--
.../group/interceptors/EncryptInterceptor.java | 11 ++++---
.../interceptors/FragmentationInterceptor.java | 2 +-
.../group/interceptors/NonBlockingCoordinator.java | 6 ++--
.../interceptors/ThroughputInterceptorMBean.java | 16 +++++-----
.../interceptors/TwoPhaseCommitInterceptor.java | 7 +++--
.../org/apache/catalina/tribes/io/ChannelData.java | 2 +-
.../apache/catalina/tribes/io/ObjectReader.java | 4 +--
.../org/apache/catalina/tribes/io/XByteBuffer.java | 8 ++---
.../apache/catalina/tribes/jmx/JmxRegistry.java | 3 +-
.../catalina/tribes/membership/Constants.java | 2 +-
.../catalina/tribes/membership/McastService.java | 15 +++++----
.../tribes/membership/McastServiceImpl.java | 7 ++---
.../catalina/tribes/membership/MemberImpl.java | 3 +-
.../catalina/tribes/membership/Membership.java | 5 ++-
.../membership/StaticMembershipServiceMBean.java | 3 +-
.../membership/cloud/AbstractStreamProvider.java | 4 ++-
.../tribes/tipis/AbstractReplicatedMap.java | 6 ++--
.../catalina/tribes/tipis/LazyReplicatedMap.java | 4 +--
.../catalina/tribes/tipis/ReplicatedMap.java | 3 --
.../catalina/tribes/tipis/ReplicatedMapEntry.java | 5 +--
.../catalina/tribes/transport/DataSender.java | 2 +-
.../catalina/tribes/transport/ReceiverBase.java | 2 +-
.../catalina/tribes/transport/RxTaskPool.java | 5 ++-
.../catalina/tribes/transport/nio/NioReceiver.java | 5 ++-
.../tribes/transport/nio/NioReplicationTask.java | 3 +-
.../catalina/tribes/transport/nio/NioSender.java | 3 +-
.../tribes/transport/nio/ParallelNioSender.java | 2 +-
.../apache/catalina/tribes/util/StringManager.java | 7 +++--
.../users/DataSourceUserDatabaseFactory.java | 13 ++++++++
.../catalina/users/MemoryUserDatabaseFactory.java | 9 +++---
java/org/apache/catalina/util/ContextName.java | 4 ++-
.../catalina/util/CustomObjectInputStream.java | 5 +--
.../apache/catalina/util/LifecycleMBeanBase.java | 2 +-
java/org/apache/catalina/util/NetMask.java | 2 +-
java/org/apache/catalina/util/NetMaskSet.java | 4 +--
.../catalina/util/SessionIdGeneratorBase.java | 3 +-
java/org/apache/catalina/util/StringUtil.java | 7 +++--
java/org/apache/catalina/util/TLSUtil.java | 2 +-
java/org/apache/catalina/util/TomcatCSS.java | 3 +-
java/org/apache/catalina/util/URLEncoder.java | 6 ++--
.../catalina/valves/AbstractAccessLogValve.java | 7 +++--
.../apache/catalina/valves/ErrorReportValve.java | 3 +-
.../catalina/valves/ExtendedAccessLogValve.java | 4 ++-
.../catalina/valves/LoadBalancerDrainingValve.java | 4 +--
.../apache/catalina/valves/LocalStrings.properties | 2 +-
.../catalina/valves/ParameterLimitValve.java | 5 +--
java/org/apache/catalina/valves/RemoteIpValve.java | 10 +++---
.../catalina/valves/StuckThreadDetectionValve.java | 4 +--
java/org/apache/catalina/valves/ValveBase.java | 4 +--
.../catalina/valves/rewrite/RewriteRule.java | 10 ++++--
.../webresources/AbstractFileResourceSet.java | 10 +++---
.../catalina/webresources/FileResourceSet.java | 4 +--
.../apache/catalina/webresources/JarContents.java | 10 +++---
.../apache/catalina/webresources/JarResource.java | 3 +-
.../catalina/webresources/LocalStrings.properties | 4 +--
.../apache/catalina/webresources/StandardRoot.java | 10 +++---
java/org/apache/coyote/AbstractProcessor.java | 2 +-
java/org/apache/coyote/AbstractProtocol.java | 3 +-
java/org/apache/coyote/ActionCode.java | 4 +--
java/org/apache/coyote/CompressionConfig.java | 4 ++-
java/org/apache/coyote/NonPipeliningProcessor.java | 4 +--
java/org/apache/coyote/ProtocolHandler.java | 1 +
java/org/apache/coyote/RequestGroupInfo.java | 6 ++--
java/org/apache/coyote/UpgradeProtocol.java | 2 +-
.../org/apache/coyote/ajp/AbstractAjpProtocol.java | 6 ++--
java/org/apache/coyote/ajp/AjpMessage.java | 3 +-
java/org/apache/coyote/ajp/AjpNioProtocol.java | 2 +-
java/org/apache/coyote/ajp/AjpProcessor.java | 4 +--
java/org/apache/coyote/http11/Http11Processor.java | 2 +-
.../coyote/http11/upgrade/LocalStrings.properties | 2 +-
.../http11/upgrade/UpgradeServletInputStream.java | 3 +-
.../http11/upgrade/UpgradeServletOutputStream.java | 3 +-
java/org/apache/coyote/http2/AbstractStream.java | 2 +-
.../coyote/http2/ConnectionSettingsBase.java | 5 ++-
.../coyote/http2/ConnectionSettingsLocal.java | 5 +--
java/org/apache/coyote/http2/HPackHuffman.java | 7 +++--
java/org/apache/coyote/http2/HpackDecoder.java | 3 +-
java/org/apache/coyote/http2/Http2Protocol.java | 2 +-
.../apache/coyote/http2/Http2UpgradeHandler.java | 4 ++-
java/org/apache/coyote/http2/StreamProcessor.java | 4 +--
.../apache/coyote/http2/StreamStateMachine.java | 6 ++--
.../coyote/http2/WindowAllocationManager.java | 2 +-
java/org/apache/el/MethodExpressionImpl.java | 9 +++---
java/org/apache/el/ValueExpressionImpl.java | 18 ++++++-----
java/org/apache/el/lang/ELSupport.java | 10 ++++--
java/org/apache/el/lang/FunctionMapperFactory.java | 6 ++--
java/org/apache/el/lang/VariableMapperFactory.java | 2 +-
java/org/apache/el/parser/AstAbstractEmpty.java | 2 +-
java/org/apache/el/parser/AstConcatenation.java | 2 +-
java/org/apache/el/parser/AstInteger.java | 6 ++--
java/org/apache/el/parser/AstMethodParameters.java | 2 +-
java/org/apache/el/parser/AstNotEmpty.java | 2 +-
java/org/apache/el/parser/AstNullCoalescing.java | 2 +-
java/org/apache/el/parser/ELParser.java | 3 +-
java/org/apache/el/parser/SimpleCharStream.java | 4 +--
java/org/apache/el/parser/TokenMgrError.java | 3 +-
java/org/apache/el/stream/Stream.java | 6 ++--
java/org/apache/el/util/ConcurrentCache.java | 2 +-
java/org/apache/el/util/ReflectionUtil.java | 10 +++---
java/org/apache/el/util/Validation.java | 2 +-
java/org/apache/jasper/JspC.java | 4 +--
java/org/apache/jasper/Options.java | 2 +-
java/org/apache/jasper/compiler/AntCompiler.java | 4 +--
java/org/apache/jasper/compiler/Compiler.java | 5 +--
java/org/apache/jasper/compiler/ELNode.java | 2 +-
java/org/apache/jasper/compiler/ELParser.java | 3 +-
.../apache/jasper/compiler/EncodingDetector.java | 3 --
java/org/apache/jasper/compiler/ErrorHandler.java | 5 ++-
java/org/apache/jasper/compiler/JDTCompiler.java | 2 +-
java/org/apache/jasper/compiler/JspReader.java | 2 +-
java/org/apache/jasper/compiler/JspUtil.java | 2 +-
java/org/apache/jasper/compiler/Node.java | 2 +-
java/org/apache/jasper/compiler/Parser.java | 2 +-
java/org/apache/jasper/compiler/SmapUtil.java | 4 ++-
.../apache/jasper/compiler/TagFileProcessor.java | 5 ++-
java/org/apache/jasper/compiler/TextOptimizer.java | 2 +-
java/org/apache/jasper/compiler/TldCache.java | 2 +-
java/org/apache/jasper/compiler/Validator.java | 2 +-
.../jasper/compiler/tagplugin/TagPlugin.java | 3 +-
.../compiler/tagplugin/TagPluginContext.java | 4 +--
java/org/apache/jasper/el/JasperELResolver.java | 7 +++--
.../optimizations/StringInterpreterEnum.java | 3 +-
.../apache/jasper/runtime/JspRuntimeLibrary.java | 6 ++--
java/org/apache/jasper/runtime/JspWriterImpl.java | 6 ++--
.../org/apache/jasper/runtime/PageContextImpl.java | 2 +-
java/org/apache/jasper/runtime/TagHandlerPool.java | 2 +-
java/org/apache/jasper/servlet/JasperLoader.java | 18 +++++------
.../apache/jasper/servlet/JspServletWrapper.java | 5 ++-
java/org/apache/jasper/tagplugins/jstl/Util.java | 11 ++++---
.../jasper/tagplugins/jstl/core/ForEach.java | 5 ++-
.../jasper/tagplugins/jstl/core/Otherwise.java | 2 +-
.../apache/jasper/tagplugins/jstl/core/Out.java | 6 ++--
.../apache/jasper/tagplugins/jstl/core/Url.java | 2 +-
.../org/apache/jasper/util/FastRemovalDequeue.java | 3 +-
java/org/apache/juli/FileHandler.java | 4 +--
java/org/apache/juli/JsonFormatter.java | 5 ++-
java/org/apache/juli/OneLineFormatter.java | 2 +-
java/org/apache/juli/logging/Log.java | 12 ++++----
java/org/apache/juli/logging/LogFactory.java | 30 +++++-------------
.../org/apache/naming/ContextAccessController.java | 4 +--
java/org/apache/naming/HandlerRef.java | 8 ++---
java/org/apache/naming/NamingContext.java | 2 +-
java/org/apache/naming/ResourceLinkRef.java | 4 +--
java/org/apache/naming/ServiceRef.java | 4 ++-
java/org/apache/naming/TransactionRef.java | 4 +--
.../naming/factory/DataSourceLinkFactory.java | 12 ++++++++
java/org/apache/naming/factory/LookupFactory.java | 2 +-
.../apache/naming/factory/MailSessionFactory.java | 16 ++++++++++
java/org/apache/naming/factory/OpenEjbFactory.java | 2 +-
.../apache/naming/factory/ResourceLinkFactory.java | 7 ++---
.../org/apache/naming/factory/SendMailFactory.java | 3 +-
.../apache/naming/java/javaURLContextFactory.java | 4 +--
java/org/apache/tomcat/InstanceManager.java | 8 ++---
.../apache/tomcat/InstrumentableClassLoader.java | 3 +-
java/org/apache/tomcat/Jar.java | 7 ++---
java/org/apache/tomcat/SimpleInstanceManager.java | 4 ++-
java/org/apache/tomcat/buildutil/Txt2Html.java | 3 +-
.../buildutil/translate/BackportEnglish.java | 5 +--
.../tomcat/buildutil/translate/Constants.java | 4 +--
.../apache/tomcat/buildutil/translate/Utils.java | 5 +--
.../dbcp/dbcp2/managed/TransactionContext.java | 2 +-
.../dbcp/dbcp2/managed/TransactionRegistry.java | 6 ++--
java/org/apache/tomcat/dbcp/pool2/TrackedUse.java | 2 +-
.../dbcp/pool2/impl/SoftReferenceObjectPool.java | 6 ++--
.../tomcat/dbcp/pool2/impl/ThrowableCallStack.java | 5 +--
java/org/apache/tomcat/jni/SSL.java | 8 ++---
java/org/apache/tomcat/jni/SSLConf.java | 2 +-
java/org/apache/tomcat/jni/SSLContext.java | 16 +++++-----
java/org/apache/tomcat/util/Diagnostics.java | 4 +--
.../org/apache/tomcat/util/IntrospectionUtils.java | 11 +++----
java/org/apache/tomcat/util/buf/AbstractChunk.java | 2 +-
java/org/apache/tomcat/util/buf/ByteChunk.java | 8 ++---
java/org/apache/tomcat/util/buf/C2BConverter.java | 2 +-
java/org/apache/tomcat/util/buf/CharChunk.java | 10 +++---
java/org/apache/tomcat/util/buf/MessageBytes.java | 11 ++++---
java/org/apache/tomcat/util/buf/StringCache.java | 8 ++---
java/org/apache/tomcat/util/buf/UDecoder.java | 2 +-
java/org/apache/tomcat/util/buf/UEncoder.java | 3 +-
java/org/apache/tomcat/util/buf/UriUtil.java | 3 +-
.../tomcat/util/collections/ConcurrentCache.java | 2 +-
java/org/apache/tomcat/util/compat/JreCompat.java | 2 +-
.../org/apache/tomcat/util/compat/JrePlatform.java | 3 +-
java/org/apache/tomcat/util/compat/JreVendor.java | 3 +-
.../concurrent/KeyedReentrantReadWriteLock.java | 2 +-
.../tomcat/util/descriptor/DigesterFactory.java | 5 +--
.../tomcat/util/descriptor/LocalResolver.java | 2 +-
.../util/descriptor/tagplugin/TagPluginParser.java | 7 +++--
.../util/descriptor/tld/ImplicitTldRuleSet.java | 2 +-
.../tomcat/util/descriptor/tld/TagFileXml.java | 2 +-
.../apache/tomcat/util/descriptor/tld/TagXml.java | 2 +-
.../tomcat/util/descriptor/tld/TldRuleSet.java | 2 +-
.../util/descriptor/web/ApplicationParameter.java | 2 +-
.../util/descriptor/web/ContextResource.java | 6 ++--
.../util/descriptor/web/ContextResourceEnvRef.java | 6 ++--
.../util/descriptor/web/ContextTransaction.java | 4 +--
.../tomcat/util/descriptor/web/ErrorPage.java | 2 +-
.../tomcat/util/descriptor/web/FilterMap.java | 2 +-
.../tomcat/util/descriptor/web/Injectable.java | 4 +--
.../tomcat/util/descriptor/web/ResourceBase.java | 3 +-
.../util/descriptor/web/SecurityConstraint.java | 5 +--
.../tomcat/util/descriptor/web/ServletDef.java | 2 +-
.../apache/tomcat/util/descriptor/web/WebXml.java | 15 ++++-----
.../util/descriptor/web/mbeans-descriptors.xml | 2 +-
.../digester/AbstractObjectCreationFactory.java | 5 +--
.../apache/tomcat/util/digester/ArrayStack.java | 5 ---
.../tomcat/util/digester/CallMethodRule.java | 22 ++++++-------
.../apache/tomcat/util/digester/CallParamRule.java | 2 +-
java/org/apache/tomcat/util/digester/Digester.java | 11 ++-----
.../util/digester/ObjectCreationFactory.java | 2 +-
java/org/apache/tomcat/util/digester/Rule.java | 4 +--
java/org/apache/tomcat/util/digester/RuleSet.java | 7 ++---
.../org/apache/tomcat/util/digester/RulesBase.java | 4 +--
.../apache/tomcat/util/file/ConfigFileLoader.java | 5 +--
java/org/apache/tomcat/util/file/Matcher.java | 4 +--
.../apache/tomcat/util/http/CookieProcessor.java | 2 +-
.../tomcat/util/http/CookiesWithoutEquals.java | 4 +--
java/org/apache/tomcat/util/http/MimeHeaders.java | 4 +--
java/org/apache/tomcat/util/http/Parameters.java | 2 +-
java/org/apache/tomcat/util/http/RequestUtil.java | 7 +++--
.../apache/tomcat/util/http/WebdavIfHeader.java | 16 +++++-----
.../http/fileupload/ThresholdingOutputStream.java | 2 +-
.../http/fileupload/util/LimitedInputStream.java | 12 ++++----
.../http/fileupload/util/mime/MimeUtility.java | 5 +--
.../tomcat/util/http/parser/AcceptLanguage.java | 2 +-
.../org/apache/tomcat/util/http/parser/Cookie.java | 4 +--
.../tomcat/util/http/parser/HttpHeaderParser.java | 4 +--
.../apache/tomcat/util/http/parser/MediaType.java | 4 ++-
.../apache/tomcat/util/http/parser/Priority.java | 2 +-
.../org/apache/tomcat/util/http/parser/Ranges.java | 2 +-
java/org/apache/tomcat/util/http/parser/TE.java | 4 +--
java/org/apache/tomcat/util/json/JSONParser.java | 6 ++--
java/org/apache/tomcat/util/json/JSONParser.jjt | 14 ++++-----
.../apache/tomcat/util/log/SystemLogHandler.java | 2 +-
.../org/apache/tomcat/util/log/UserDataHelper.java | 7 +++--
.../apache/tomcat/util/modeler/BaseModelMBean.java | 10 +++---
.../apache/tomcat/util/modeler/ManagedBean.java | 2 +-
.../tomcat/util/modeler/NotificationInfo.java | 4 +--
.../apache/tomcat/util/modeler/OperationInfo.java | 2 +-
java/org/apache/tomcat/util/modeler/Registry.java | 10 +++---
.../apache/tomcat/util/modeler/RegistryMBean.java | 8 ++---
.../MbeansDescriptorsIntrospectionSource.java | 7 +----
.../tomcat/util/modeler/modules/ModelerSource.java | 2 +-
java/org/apache/tomcat/util/net/NioEndpoint.java | 8 ++---
.../apache/tomcat/util/net/SecureNioChannel.java | 6 ++--
.../apache/tomcat/util/net/SendfileDataBase.java | 2 +-
.../apache/tomcat/util/net/SocketProperties.java | 11 ++++---
.../apache/tomcat/util/net/SocketWrapperBase.java | 12 ++++----
java/org/apache/tomcat/util/net/jsse/PEMFile.java | 8 +++--
.../tomcat/util/net/openssl/OpenSSLEngine.java | 1 -
.../tomcat/util/net/openssl/ciphers/Cipher.java | 9 +++---
.../util/net/openssl/ciphers/Encryption.java | 2 +-
.../util/net/openssl/ciphers/KeyExchange.java | 2 +-
.../ciphers/OpenSSLCipherConfigurationParser.java | 6 ++--
.../util/net/openssl/panama/OpenSSLEngine.java | 2 +-
.../tomcat/util/openssl/openssl_h_Macros.java | 6 ++--
java/org/apache/tomcat/util/res/StringManager.java | 14 ++++++---
.../tomcat/util/scan/NonClosingJarInputStream.java | 2 +-
.../tomcat/util/scan/StandardJarScanFilter.java | 2 +-
.../tomcat/util/scan/StandardJarScanner.java | 4 +--
java/org/apache/tomcat/util/security/Escape.java | 2 +-
.../tomcat/util/security/LocalStrings.properties | 2 +-
.../org/apache/tomcat/util/threads/LimitLatch.java | 6 ++--
java/org/apache/tomcat/util/threads/TaskQueue.java | 20 ++++++++++--
.../tomcat/util/threads/ThreadPoolExecutor.java | 6 ++--
.../ObjectReflectionPropertyInspector.java | 5 +--
.../websocket/AsyncChannelWrapperSecure.java | 3 +-
.../org/apache/tomcat/websocket/Authenticator.java | 2 +-
java/org/apache/tomcat/websocket/Constants.java | 2 +-
.../apache/tomcat/websocket/PerMessageDeflate.java | 3 +-
java/org/apache/tomcat/websocket/Util.java | 14 +++++----
java/org/apache/tomcat/websocket/WsFrameBase.java | 6 ++--
java/org/apache/tomcat/websocket/WsSession.java | 12 ++++----
.../tomcat/websocket/WsWebSocketContainer.java | 2 +-
.../tomcat/websocket/pojo/PojoMethodMapping.java | 7 +++--
.../tomcat/websocket/pojo/PojoPathParam.java | 4 +--
.../tomcat/websocket/server/WsFrameServer.java | 2 +-
.../tomcat/websocket/server/WsServerContainer.java | 4 +--
test/org/apache/juli/TestJsonFormatter.java | 1 +
webapps/docs/config/context.xml | 2 +-
webapps/docs/config/listeners.xml | 7 +++--
webapps/docs/monitoring.xml | 22 ++++++-------
webapps/docs/rewrite.xml | 2 +-
420 files changed, 1170 insertions(+), 1022 deletions(-)
diff --git a/java/org/apache/catalina/Container.java b/java/org/apache/catalina/Container.java
index 0ad0da0270..8a34c5cc18 100644
--- a/java/org/apache/catalina/Container.java
+++ b/java/org/apache/catalina/Container.java
@@ -165,9 +165,9 @@ public interface Container extends Lifecycle {
/**
* Get the delay between the invocation of the backgroundProcess method on this container and its children. Child
* containers will not be invoked if their delay value is positive (which would mean they are using their own
- * thread). Setting this to a positive value will cause a thread to be spawned. After waiting the specified amount
- * of time, the thread will invoke the {@link #backgroundProcess()} method on this container and all children with
- * non-positive delay values.
+ * thread). A positive value causes a thread to be spawned. After waiting the specified amount of time, the thread
+ * will invoke the {@link #backgroundProcess()} method on this container and all children with non-positive delay
+ * values.
*
* @return The delay between the invocation of the backgroundProcess method on this container and its children. A
* non-positive value indicates that background processing will be managed by the parent.
@@ -176,7 +176,7 @@ public interface Container extends Lifecycle {
/**
- * Set the delay between the invocation of the execute method on this container and its children.
+ * Set the delay between the invocation of the backgroundProcess method on this container and its children.
*
* @param delay The delay in seconds between the invocation of backgroundProcess methods
*/
diff --git a/java/org/apache/catalina/Context.java b/java/org/apache/catalina/Context.java
index c403dad8f3..99b081b683 100644
--- a/java/org/apache/catalina/Context.java
+++ b/java/org/apache/catalina/Context.java
@@ -72,7 +72,7 @@ public interface Context extends Container, ContextBind {
String ADD_WELCOME_FILE_EVENT = "addWelcomeFile";
/**
- * Container event for removing a wrapper.
+ * Container event for removing a welcome file.
*/
String REMOVE_WELCOME_FILE_EVENT = "removeWelcomeFile";
@@ -95,10 +95,10 @@ public interface Context extends Container, ContextBind {
// ------------------------------------------------------------- Properties
/**
- * Returns <code>true</code> if requests mapped to servlets without "multipart config" to parse multipart/form-data
+ * Returns <code>true</code> if requests mapped to servlets without "multipart config" will parse multipart/form-data
* requests anyway.
*
- * @return <code>true</code> if requests mapped to servlets without "multipart config" to parse multipart/form-data
+ * @return <code>true</code> if requests mapped to servlets without "multipart config" will parse multipart/form-data
* requests, <code>false</code> otherwise.
*/
boolean getAllowCasualMultipartParsing();
@@ -596,7 +596,7 @@ public interface Context extends Container, ContextBind {
/**
- * Returns <code>true</code> if remaining request data will be read (swallowed) even the request violates a data
+ * Returns <code>true</code> if remaining request data will be read (swallowed) even if the request violates a data
* size constraint.
*
* @return <code>true</code> if data will be swallowed (default), <code>false</code> otherwise.
@@ -1957,9 +1957,9 @@ public interface Context extends Container, ContextBind {
/**
- * Find configuration file with the specified path, first looking into the webapp resources, then delegating to
- * <code>ConfigFileLoader.getSource().getResource</code>. The <code>WEBAPP_PROTOCOL</code> constant prefix is used
- * to denote webapp resources.
+ * Find configuration file with the specified path. Names with the <code>WEBAPP_PROTOCOL</code> constant prefix are
+ * resolved against the webapp resources only. Any other name is resolved by delegating to
+ * <code>ConfigFileLoader.getSource().getResource</code>.
*
* @param name The resource name
*
diff --git a/java/org/apache/catalina/DistributedManager.java b/java/org/apache/catalina/DistributedManager.java
index ccf4f24072..00fc14c3eb 100644
--- a/java/org/apache/catalina/DistributedManager.java
+++ b/java/org/apache/catalina/DistributedManager.java
@@ -39,9 +39,9 @@ public interface DistributedManager {
int getActiveSessionsFull();
/**
- * Returns the list of all sessions IDS (primary, backup and proxy).
+ * Returns the set of all session IDs (primary, backup and proxy).
*
- * @return The complete set of sessions IDs across the cluster.
+ * @return The complete set of session IDs across the cluster.
*/
Set<String> getSessionIdsFull();
}
diff --git a/java/org/apache/catalina/Engine.java b/java/org/apache/catalina/Engine.java
index bba5af7803..c02cc4a559 100644
--- a/java/org/apache/catalina/Engine.java
+++ b/java/org/apache/catalina/Engine.java
@@ -28,7 +28,7 @@ package org.apache.catalina;
* Wrapper) should be utilized to process this request.
* <p>
* The child containers attached to an Engine are generally implementations of Host (representing a virtual host) or
- * Context (representing individual an individual servlet context), depending upon the Engine implementation.
+ * Context (representing an individual servlet context), depending upon the Engine implementation.
* <p>
* If used, an Engine is always the top level Container in a Catalina hierarchy. Therefore, the implementation's
* <code>setParent()</code> method should throw <code>IllegalArgumentException</code>.
diff --git a/java/org/apache/catalina/Host.java b/java/org/apache/catalina/Host.java
index 45f4f8ebb9..5007eb70e6 100644
--- a/java/org/apache/catalina/Host.java
+++ b/java/org/apache/catalina/Host.java
@@ -76,7 +76,9 @@ public interface Host extends Container {
void setXmlBase(String xmlBase);
/**
- * Get the default configuration path of this Host. The file will be canonical if possible.
+ * Get the configuration path of this Host. If a base path has been configured via {@link #setXmlBase(String)},
+ * that value is returned. Otherwise, the default path
+ * ${catalina.base}/conf/<engine name>/<host name> is returned. The file will be canonical if possible.
*
* @return the configuration base file
*/
@@ -169,7 +171,7 @@ public interface Host extends Container {
/**
* Get the value of the deploy on startup flag. If true, it indicates that this host's child webapps should be
- * discovered and automatically deployed.
+ * discovered and deployed when the Host starts, independently of the auto deploy flag.
*
* @return the deploy on startup flag
*/
diff --git a/java/org/apache/catalina/Lifecycle.java b/java/org/apache/catalina/Lifecycle.java
index 8e9b91f9a8..859bd8883b 100644
--- a/java/org/apache/catalina/Lifecycle.java
+++ b/java/org/apache/catalina/Lifecycle.java
@@ -69,11 +69,13 @@ package org.apache.catalina;
* does not start all its sub-components. When the component is stopped, it will
* try to stop all sub-components - even those it didn't start.
*
- * Attempting any other transition will throw {@link LifecycleException}.
+ * Attempting any other transition will throw {@link LifecycleException},
+ * except calling stop() while a component is in state INITIALIZED which has
+ * no effect.
*
* </pre>
*
- * The {@link LifecycleEvent}s fired during state changes are defined in the methods that trigger the changed. No
+ * The {@link LifecycleEvent}s fired during state changes are defined in the methods that trigger the change. No
* {@link LifecycleEvent}s are fired if the attempted transition is not valid.
*/
public interface Lifecycle {
diff --git a/java/org/apache/catalina/Manager.java b/java/org/apache/catalina/Manager.java
index 69b02d066c..12967fd23a 100644
--- a/java/org/apache/catalina/Manager.java
+++ b/java/org/apache/catalina/Manager.java
@@ -220,8 +220,7 @@ public interface Manager {
/**
* Construct and return a new session object, based on the default settings specified by this Manager's properties.
- * The session id specified will be used as the session id. If a new session cannot be created for any reason,
- * return <code>null</code>.
+ * The session id specified will be used as the session id.
*
* @param sessionId The session id which should be used to create the new session; if <code>null</code>, the session
* id will be assigned by this method, and available via the getId() method of the returned
@@ -240,8 +239,7 @@ public interface Manager {
*
* @param id The session id for the session to be returned
*
- * @exception IllegalStateException if a new session cannot be instantiated for any reason
- * @exception IOException if an input/output error occurs while processing this request
+ * @exception IOException if an input/output error occurs while processing this request
*
* @return the request session or {@code null} if a session with the requested ID could not be found
*/
diff --git a/java/org/apache/catalina/Server.java b/java/org/apache/catalina/Server.java
index 1aac24f810..4aa3ee51c2 100644
--- a/java/org/apache/catalina/Server.java
+++ b/java/org/apache/catalina/Server.java
@@ -32,8 +32,8 @@ import org.apache.catalina.startup.Catalina;
* started or stopped.
* <p>
* In between, the implementation must open a server socket on the port number specified by the <code>port</code>
- * property. When a connection is accepted, the first line is read and compared with the specified shutdown command. If
- * the command matches, shutdown of the server is initiated.
+ * property (plus the <code>portOffset</code>, if set). When a connection is accepted, the first line is read and
+ * compared with the specified shutdown command. If the command matches, shutdown of the server is initiated.
*/
public interface Server extends Lifecycle {
@@ -93,7 +93,7 @@ public interface Server extends Lifecycle {
/**
* Set the number that offsets the server port used for shutdown commands. For example, if port is 8005, and you set
- * portOffset to 1000, connector listens at 9005.
+ * portOffset to 1000, the server listens at 9005.
*
* @param portOffset sets the port offset
*/
diff --git a/java/org/apache/catalina/Store.java b/java/org/apache/catalina/Store.java
index db021b006e..5d8009fa4c 100644
--- a/java/org/apache/catalina/Store.java
+++ b/java/org/apache/catalina/Store.java
@@ -50,7 +50,7 @@ public interface Store {
*
* @return the number of Sessions
*
- * @exception IOException if an input/output error occurs
+ * @throws IOException if an input/output error occurs
*/
int getSize() throws IOException;
@@ -69,7 +69,7 @@ public interface Store {
*
* @return the session identifiers
*
- * @exception IOException if an input/output error occurred
+ * @throws IOException if an input/output error occurred
*/
String[] keys() throws IOException;
@@ -85,8 +85,8 @@ public interface Store {
*
* @param id Session identifier of the session to load
*
- * @exception ClassNotFoundException if a deserialization error occurs
- * @exception IOException if an input/output error occurs
+ * @throws ClassNotFoundException if a deserialization error occurs
+ * @throws IOException if an input/output error occurs
*
* @return the loaded Session instance
*/
@@ -104,7 +104,7 @@ public interface Store {
*
* @param id Session identifier of the Session to be removed
*
- * @exception IOException if an input/output error occurs
+ * @throws IOException if an input/output error occurs
*/
void remove(String id) throws IOException;
@@ -112,7 +112,7 @@ public interface Store {
/**
* Remove all Sessions from this Store.
*
- * @exception IOException if an input/output error occurs
+ * @throws IOException if an input/output error occurs
*/
void clear() throws IOException;
@@ -134,7 +134,7 @@ public interface Store {
*
* @param session Session to be saved
*
- * @exception IOException if an input/output error occurs
+ * @throws IOException if an input/output error occurs
*/
void save(Session session) throws IOException;
diff --git a/java/org/apache/catalina/User.java b/java/org/apache/catalina/User.java
index 15c729811e..db0579e326 100644
--- a/java/org/apache/catalina/User.java
+++ b/java/org/apache/catalina/User.java
@@ -62,14 +62,14 @@ public interface User extends Principal {
* Returns the logon password of this user.
*
* @return the logon password of this user, optionally prefixed with the identifier of an encoding scheme surrounded
- * by curly braces, such as <code>{md5}xxxxx</code>.
+ * by curly braces, such as <code>{MD5}xxxxx</code>.
*/
String getPassword();
/**
* Set the logon password of this user, optionally prefixed with the identifier of an encoding scheme surrounded by
- * curly braces, such as <code>{md5}xxxxx</code>.
+ * curly braces, such as <code>{MD5}xxxxx</code>.
*
* @param password The new logon password
*/
@@ -101,7 +101,9 @@ public interface User extends Principal {
/**
- * Set the logon username of this user, which must be unique within the scope of a {@link UserDatabase}.
+ * Set the logon username of this user, which must be unique within the scope of a {@link UserDatabase}. The
+ * standard implementations treat the username as immutable and ignore this method; to change a user's username
+ * the user must be removed from, and then re-added to, the database.
*
* @param username The new logon username
*/
diff --git a/java/org/apache/catalina/UserDatabase.java b/java/org/apache/catalina/UserDatabase.java
index e8ea24ae11..07bd842e7b 100644
--- a/java/org/apache/catalina/UserDatabase.java
+++ b/java/org/apache/catalina/UserDatabase.java
@@ -211,7 +211,7 @@ public interface UserDatabase {
/**
* Is the database available.
*
- * @return true
+ * @return <code>true</code> if the database is available, <code>false</code> otherwise
*/
default boolean isAvailable() {
return true;
diff --git a/java/org/apache/catalina/WebResourceLockSet.java b/java/org/apache/catalina/WebResourceLockSet.java
index 22ed9e280d..b2db4943e5 100644
--- a/java/org/apache/catalina/WebResourceLockSet.java
+++ b/java/org/apache/catalina/WebResourceLockSet.java
@@ -25,8 +25,8 @@ public interface WebResourceLockSet {
/**
* Obtain a reentrant read/write lock for the resource at the provided path. The resource is not required to exist.
- * Multiple calls to this method with the same path will return the same lock provided that at least one instance of
- * the lock remains in use between the calls.
+ * Multiple calls to this method with the same path will return locks that share the same underlying read/write
+ * lock provided that at least one instance of the lock remains in use between the calls.
*
* @param path The path for which the lock should be obtained
*
diff --git a/java/org/apache/catalina/WebResourceRoot.java b/java/org/apache/catalina/WebResourceRoot.java
index 3ce8795b2c..95de68b721 100644
--- a/java/org/apache/catalina/WebResourceRoot.java
+++ b/java/org/apache/catalina/WebResourceRoot.java
@@ -69,7 +69,9 @@ import org.apache.catalina.util.ResourceSet;
public interface WebResourceRoot extends Lifecycle {
/**
* Obtain the object that represents the resource at the given path. Note that the resource at that path may not
- * exist. If the resource does not exist, the WebResource returned will be associated with the main WebResourceSet.
+ * exist. If the resource does not exist and a virtual resource is defined for the path, the WebResource returned
+ * will be associated with the WebResourceSet that defines the virtual resource. Otherwise, it will be associated
+ * with the main WebResourceSet.
*
* @param path The path for the resource of interest relative to the root of the web application. It must start with
* '/'.
@@ -369,7 +371,7 @@ public interface WebResourceRoot extends Lifecycle {
/**
* Get the strategy to use for the resources archive lookup.
*
- * @return The strategy to use for the resources archive lookup
+ * @return The strategy, as an {@link ArchiveIndexStrategy}, to use for the resources archive lookup
*/
ArchiveIndexStrategy getArchiveIndexStrategyEnum();
diff --git a/java/org/apache/catalina/Wrapper.java b/java/org/apache/catalina/Wrapper.java
index bd6f0debd1..3454da3c01 100644
--- a/java/org/apache/catalina/Wrapper.java
+++ b/java/org/apache/catalina/Wrapper.java
@@ -65,8 +65,8 @@ public interface Wrapper extends Container {
/**
* Set the available date/time for this servlet, in milliseconds since the epoch. If this date/time is in the
- * future, any request for this servlet will return an SC_SERVICE_UNAVAILABLE error. A value equal to Long.MAX_VALUE
- * is considered to mean that unavailability is permanent.
+ * future, any request for this servlet will return an SC_SERVICE_UNAVAILABLE error. If it is zero, the servlet is
+ * currently available. A value equal to Long.MAX_VALUE is considered to mean that unavailability is permanent.
*
* @param available The new available date/time
*/
diff --git a/java/org/apache/catalina/ant/AbstractCatalinaTask.java b/java/org/apache/catalina/ant/AbstractCatalinaTask.java
index 85e6b7608d..5fc185117c 100644
--- a/java/org/apache/catalina/ant/AbstractCatalinaTask.java
+++ b/java/org/apache/catalina/ant/AbstractCatalinaTask.java
@@ -35,9 +35,7 @@ import org.apache.tools.ant.Project;
/**
* Abstract base class for Ant tasks that interact with the <em>Manager</em> web application for dynamically deploying
- * and undeploying applications. These tasks require Ant 1.4 or later.
- *
- * @since 4.1
+ * and undeploying applications. These tasks require Ant 1.5 or later.
*/
public abstract class AbstractCatalinaTask extends BaseRedirectorHelperTask {
@@ -333,8 +331,9 @@ public abstract class AbstractCatalinaTask extends BaseRedirectorHelperTask {
* the above two are not compatible. When the request is made, the resulting 401 triggers an exception because, when
* using streams, the InputStream is no longer available to send with the repeated request that now includes the
* appropriate Authorization header. The hack is to make a simple OPTIONS request- i.e. without a request body. This
- * triggers authentication and the requirement to authenticate for this host is cached in the Authenticator and used
- * to provide an appropriate Authorization when the next request is made (that includes a request body).
+ * triggers authentication and the requirement to authenticate for this host is cached in the JDK's HTTP
+ * authentication cache and used to provide an appropriate Authorization when the next request is made (that
+ * includes a request body).
*/
private void preAuthenticate(Authenticator authenticator) throws IOException, URISyntaxException {
diff --git a/java/org/apache/catalina/ant/BaseRedirectorHelperTask.java b/java/org/apache/catalina/ant/BaseRedirectorHelperTask.java
index 1f6b30601b..8dd5b68a64 100644
--- a/java/org/apache/catalina/ant/BaseRedirectorHelperTask.java
+++ b/java/org/apache/catalina/ant/BaseRedirectorHelperTask.java
@@ -101,7 +101,7 @@ public abstract class BaseRedirectorHelperTask extends Task {
/**
* Returns the value of the failOnError property.
*
- * @return <code>true</code> if the task should will if an error occurs, otherwise <code>false</code>
+ * @return <code>true</code> if the task should fail if an error occurs, otherwise <code>false</code>
*/
public boolean isFailOnError() {
return failOnError;
diff --git a/java/org/apache/catalina/ant/JKStatusUpdateTask.java b/java/org/apache/catalina/ant/JKStatusUpdateTask.java
index 45e6cb70b1..767a88bf8b 100644
--- a/java/org/apache/catalina/ant/JKStatusUpdateTask.java
+++ b/java/org/apache/catalina/ant/JKStatusUpdateTask.java
@@ -332,11 +332,11 @@ public class JKStatusUpdateTask extends AbstractCatalinaTask {
if (isLBMode) {
// http://localhost/status?cmd=update&mime=txt&w=lb&lf=false&ls=true
- if ((lbRetries != null)) { // > 0
+ if ((lbRetries != null)) { // > 1
sb.append("&lr=");
sb.append(lbRetries);
}
- if ((lbRecovertime != null)) { // > 59
+ if ((lbRecovertime != null)) { // >= 60
sb.append("<=");
sb.append(lbRecovertime);
}
diff --git a/java/org/apache/catalina/ant/SessionsTask.java b/java/org/apache/catalina/ant/SessionsTask.java
index 7251b4d52b..a6bf92c602 100644
--- a/java/org/apache/catalina/ant/SessionsTask.java
+++ b/java/org/apache/catalina/ant/SessionsTask.java
@@ -19,7 +19,8 @@ package org.apache.catalina.ant;
import org.apache.tools.ant.BuildException;
/**
- * Ant task that implements the <code>/sessions</code> command supported by the Tomcat manager application.
+ * Ant task that implements the <code>/sessions</code> command supported by the Tomcat manager application. Note that
+ * the <code>/sessions</code> command is deprecated in favour of the <code>/expire</code> command.
*/
public class SessionsTask extends AbstractCatalinaCommandTask {
@@ -30,12 +31,12 @@ public class SessionsTask extends AbstractCatalinaCommandTask {
}
/**
- * Minimum idle time in minutes for sessions to be included in the response.
+ * Minimum idle time in minutes for sessions to be expired (invalidated).
*/
protected String idle = null;
/**
- * Returns the minimum idle time in minutes for sessions to be included.
+ * Returns the minimum idle time in minutes for sessions to be expired (invalidated).
*
* @return the minimum idle time
*/
@@ -44,7 +45,7 @@ public class SessionsTask extends AbstractCatalinaCommandTask {
}
/**
- * Sets the minimum idle time in minutes for sessions to be included.
+ * Sets the minimum idle time in minutes for sessions to be expired (invalidated).
*
* @param idle the minimum idle time
*/
diff --git a/java/org/apache/catalina/ant/ValidatorTask.java b/java/org/apache/catalina/ant/ValidatorTask.java
index 9dac71e3c3..201d931119 100644
--- a/java/org/apache/catalina/ant/ValidatorTask.java
+++ b/java/org/apache/catalina/ant/ValidatorTask.java
@@ -97,7 +97,6 @@ public class ValidatorTask extends BaseRedirectorHelperTask {
ClassLoader oldCL = currentThread.getContextClassLoader();
currentThread.setContextClassLoader(ValidatorTask.class.getClassLoader());
- // Called through trusted manager interface.
Digester digester = DigesterFactory.newDigester(true, true, null, false);
try (InputStream stream = new BufferedInputStream(new FileInputStream(file.getCanonicalFile()))) {
InputSource is = new InputSource(file.toURI().toURL().toExternalForm());
diff --git a/java/org/apache/catalina/ant/jmx/JMXAccessorCreateTask.java b/java/org/apache/catalina/ant/jmx/JMXAccessorCreateTask.java
index 18bc588615..9513f69b1f 100644
--- a/java/org/apache/catalina/ant/jmx/JMXAccessorCreateTask.java
+++ b/java/org/apache/catalina/ant/jmx/JMXAccessorCreateTask.java
@@ -43,7 +43,7 @@ import org.apache.tools.ant.BuildException;
* className="org.apache.catalina.mbeans.MBeanFactory"
* classLoader="Catalina:type=ServerClassLoader,name=server">
* <Arg value="org.apache.catalina.mbeans.MBeanFactory" />
- * </jmxCreate/>
+ * </jmx:create>
* </pre>
* <p>
* <b>WARNING</b>Not all Tomcat MBeans can create remotely and auto register by its parents! Please, use the
diff --git a/java/org/apache/catalina/ant/jmx/JMXAccessorGetTask.java b/java/org/apache/catalina/ant/jmx/JMXAccessorGetTask.java
index 78fe5dfece..4249d695c0 100644
--- a/java/org/apache/catalina/ant/jmx/JMXAccessorGetTask.java
+++ b/java/org/apache/catalina/ant/jmx/JMXAccessorGetTask.java
@@ -41,11 +41,10 @@ import org.apache.tools.ant.BuildException;
* name="Catalina:type=IDataSender,host=localhost,senderAddress=192.168.1.2,senderPort=9025"
* attribute="nrOfRequests"
* resultproperty="IDataSender.9025.nrOfRequests"
- * echo="false">
- * />
+ * echo="false" />
* </pre>
* <p>
- * First call to a remote MBeanserver save the JMXConnection a referenz <em>jmx.server</em>
+ * First call to a remote MBeanserver save the JMXConnection a reference <em>jmx.server</em>
* </p>
* These tasks require Ant 1.6 or later interface.
*
diff --git a/java/org/apache/catalina/ant/jmx/JMXAccessorInvokeTask.java b/java/org/apache/catalina/ant/jmx/JMXAccessorInvokeTask.java
index f1d0c50eb7..092c9011e9 100644
--- a/java/org/apache/catalina/ant/jmx/JMXAccessorInvokeTask.java
+++ b/java/org/apache/catalina/ant/jmx/JMXAccessorInvokeTask.java
@@ -78,7 +78,7 @@ import org.apache.tools.ant.BuildException;
* </li>
* </ul>
* <p>
- * First call to a remote MBeanserver save the JMXConnection a referenz <em>jmx.server</em>
+ * First call to a remote MBeanserver save the JMXConnection a reference <em>jmx.server</em>
* </p>
* These tasks require Ant 1.6 or later interface.
*
diff --git a/java/org/apache/catalina/ant/jmx/JMXAccessorQueryTask.java b/java/org/apache/catalina/ant/jmx/JMXAccessorQueryTask.java
index 7e70bb7287..303aaa717d 100644
--- a/java/org/apache/catalina/ant/jmx/JMXAccessorQueryTask.java
+++ b/java/org/apache/catalina/ant/jmx/JMXAccessorQueryTask.java
@@ -30,7 +30,7 @@ import org.apache.tools.ant.BuildException;
/**
* Query for Mbeans.
* <ul>
- * <li>open no existing JSR 160 rmi jmx connection</li>
+ * <li>reuse existing JSR 160 rmi jmx connection</li>
* <li>Get all Mbeans attributes</li>
* <li>Get only the Query Mbeans ObjectNames</li>
* <li>Show query result as Ant console log</li>
@@ -43,12 +43,12 @@ import org.apache.tools.ant.BuildException;
* <jmxQuery
* host="127.0.0.1"
* port="9014"
- * name="Catalina:type=Manager,*
+ * name="Catalina:type=Manager,*"
* resultproperty="manager" />
* </pre>
*
* with attribute <em>attributebinding="true"</em> you can get all attributes also from result objects.<br>
- * The property manager.length show the size of the result and with manager.[0..length].name the resulted ObjectNames
+ * The property manager.Length show the size of the result and with manager.[0..Length].Name the resulted ObjectNames
* are saved. These tasks require Ant 1.6 or later interface.
*
* @since 5.5.10
diff --git a/java/org/apache/catalina/ant/jmx/JMXAccessorSetTask.java b/java/org/apache/catalina/ant/jmx/JMXAccessorSetTask.java
index b09de55dd7..96f1bae2f5 100644
--- a/java/org/apache/catalina/ant/jmx/JMXAccessorSetTask.java
+++ b/java/org/apache/catalina/ant/jmx/JMXAccessorSetTask.java
@@ -29,9 +29,9 @@ import org.apache.tools.ant.BuildException;
/**
* Access <em>JMX</em> JSR 160 MBeans Server.
* <ul>
- * <li>Get Mbeans attributes</li>
- * <li>Show Get result as Ant console log</li>
- * <li>Bind Get result as Ant properties</li>
+ * <li>Set Mbeans attributes</li>
+ * <li>Show Set result as Ant console log</li>
+ * <li>Bind Set result as Ant properties</li>
* </ul>
* <p>
* Examples: Set a Mbean Manager attribute maxActiveSessions. Set this attribute with fresh jmx connection without save
@@ -43,12 +43,11 @@ import org.apache.tools.ant.BuildException;
* host="127.0.0.1"
* port="9014"
* ref=""
- * name="Catalina:type=Manager,context="/ClusterTest",host=localhost"
+ * name="Catalina:type=Manager,context="/ClusterTest",host=localhost"
* attribute="maxActiveSessions"
* value="100"
* type="int"
- * echo="false">
- * />
+ * echo="false" />
* </pre>
* <p>
* First call to a remote MBean server save the JMXConnection a reference <em>jmx.server</em>
diff --git a/java/org/apache/catalina/ant/jmx/JMXAccessorTask.java b/java/org/apache/catalina/ant/jmx/JMXAccessorTask.java
index 007a9c1c5f..91d66c4ef8 100644
--- a/java/org/apache/catalina/ant/jmx/JMXAccessorTask.java
+++ b/java/org/apache/catalina/ant/jmx/JMXAccessorTask.java
@@ -69,7 +69,7 @@ import org.apache.tools.ant.Project;
*
* All calls after opening with same refid reuse the connection.
* <p>
- * First call to a remote MBeanserver save the JMXConnection a referenz <em>jmx.server</em>
+ * First call to a remote MBeanserver save the JMXConnection a reference <em>jmx.server</em>
* </p>
* All JMXAccessorXXXTask support the attribute <em>if</em> and <em>unless</em>. With <em>if</em> the task is only
* execute when property exist and with <em>unless</em> when property not exists. <br>
@@ -540,8 +540,7 @@ public class JMXAccessorTask extends BaseRedirectorHelperTask {
}
/**
- * Execute the specified command, based on the configured properties. The input stream will be closed upon
- * completion of this task, whether it was executed successfully or not.
+ * Execute the specified command, based on the configured properties.
*
* @param jmxServerConnection The JMX connection that should be used
*
@@ -659,8 +658,8 @@ public class JMXAccessorTask extends BaseRedirectorHelperTask {
/**
* create result as property with name from property prefix When result is an array and isSeparateArrayResults is
- * true, resultproperty used as prefix (<code>resultproperty.0-array.length</code> and store the result array length
- * at <code>resultproperty.length</code>. Other option is that you delimit your result with a delimiter
+ * true, resultproperty used as prefix (<code>resultproperty.0-array.Length</code> and store the result array length
+ * at <code>resultproperty.Length</code>. Other option is that you delimit your result with a delimiter
* (java.util.StringTokenizer is used).
*
* @param propertyPrefix Prefix for the property
diff --git a/java/org/apache/catalina/ant/jmx/JMXAccessorUnregisterTask.java b/java/org/apache/catalina/ant/jmx/JMXAccessorUnregisterTask.java
index ad7e47ac00..d0ebe5132f 100644
--- a/java/org/apache/catalina/ant/jmx/JMXAccessorUnregisterTask.java
+++ b/java/org/apache/catalina/ant/jmx/JMXAccessorUnregisterTask.java
@@ -24,7 +24,7 @@ import org.apache.tools.ant.BuildException;
/**
* unregister an MBean at <em>JMX</em> JSR 160 MBeans Server.
* <ul>
- * <li>unregister Mbeans</li>
+ * <li>unregister MBean</li>
* </ul>
* <p>
* Examples: <br>
@@ -37,11 +37,12 @@ import org.apache.tools.ant.BuildException;
* name="Catalina:type=MBeanFactory" />
* </pre>
* <p>
- * <b>WARNING</b>Not all Tomcat MBeans can successfully unregister remotely. The mbean unregistration don't remove
+ * <b>WARNING</b>Not all Tomcat MBeans can successfully unregister remotely. The MBean unregistration does not remove
* valves, realm, .. from parent class. Please, use the MBeanFactory operation to remove valves and realms.
* </p>
* <p>
- * First call to a remote MBeanserver save the JMXConnection a reference <em>jmx.server</em>
+ * As with the other JMX accessor tasks, the first call to a remote MBean server saves the JMXConnection under the
+ * reference <em>jmx.server</em> as a side effect of the shared connection handling in the parent class.
* </p>
* These tasks require Ant 1.6 or later interface.
*
diff --git a/java/org/apache/catalina/authenticator/AuthenticatorBase.java b/java/org/apache/catalina/authenticator/AuthenticatorBase.java
index 9378267a08..f376a49fce 100644
--- a/java/org/apache/catalina/authenticator/AuthenticatorBase.java
+++ b/java/org/apache/catalina/authenticator/AuthenticatorBase.java
@@ -558,7 +558,7 @@ public abstract class AuthenticatorBase extends ValveBase implements Authenticat
hasAuthConstraint = true;
for (int i = 0; i < constraints.length && hasAuthConstraint; i++) {
if (constraints[i].getAllRoles() || constraints[i].getAuthenticatedUsers()) {
- // NO-OP - has hasAuthConstraint
+ // NO-OP - hasAuthConstraint remains true
} else if (!constraints[i].getAuthConstraint()) {
hasAuthConstraint = false;
} else {
diff --git a/java/org/apache/catalina/authenticator/BasicAuthenticator.java b/java/org/apache/catalina/authenticator/BasicAuthenticator.java
index 551be88926..6e39d89b2c 100644
--- a/java/org/apache/catalina/authenticator/BasicAuthenticator.java
+++ b/java/org/apache/catalina/authenticator/BasicAuthenticator.java
@@ -50,9 +50,10 @@ public class BasicAuthenticator extends AuthenticatorBase {
/**
- * Returns the character set used for encoding credentials, as set by the user.
+ * Returns the character set name used for encoding credentials, as set by the user.
*
- * @return the character set name, the default value is "UTF-8"
+ * @return the character set name, the default value is "UTF-8". May be <code>null</code> or empty, in which case
+ * the credentials are encoded using ISO-8859-1.
*/
public String getCharset() {
return charsetString;
@@ -140,7 +141,7 @@ public class BasicAuthenticator extends AuthenticatorBase {
/**
- * Parser for an HTTP Authorization header for BASIC authentication as per RFC 2617 section 2, and the Base64
+ * Parser for an HTTP Authorization header for BASIC authentication as per RFC 7617, and the Base64
* encoded credentials as per RFC 2045 section 6.8.
*/
public static class BasicCredentials {
@@ -209,9 +210,9 @@ public class BasicAuthenticator extends AuthenticatorBase {
}
/*
- * Decode the base64-user-pass token, which RFC 2617 states can be longer than the 76 characters per line limit
- * defined in RFC 2045. The base64 decoder will ignore embedded line break characters as well as surplus
- * surrounding white space.
+ * Decode the base64-user-pass token, which RFC 7617 states can be longer than the 76 characters per line limit
+ * defined in RFC 2045. The base64 decoder is a strict decoder that rejects any embedded line break characters
+ * as well as surplus surrounding white space.
*/
private byte[] parseBase64() throws IllegalArgumentException {
byte[] encoded = new byte[base64blobLength];
diff --git a/java/org/apache/catalina/authenticator/DigestAuthenticator.java b/java/org/apache/catalina/authenticator/DigestAuthenticator.java
index 6e175c7907..112851de47 100644
--- a/java/org/apache/catalina/authenticator/DigestAuthenticator.java
+++ b/java/org/apache/catalina/authenticator/DigestAuthenticator.java
@@ -139,7 +139,7 @@ public class DigestAuthenticator extends AuthenticatorBase {
/**
- * Should the URI be validated as required by RFC2617? Can be disabled in reverse proxies where the proxy has
+ * Should the URI be validated as required by RFC 7616? Can be disabled in reverse proxies where the proxy has
* modified the URI.
*/
protected boolean validateUri = true;
@@ -388,8 +388,8 @@ public class DigestAuthenticator extends AuthenticatorBase {
/**
- * Generate a unique token. The token is generated according to the following pattern. NOnceToken = Base64 (
- * NONCE_DIGEST ( client-IP ":" time-stamp ":" private-key ) ).
+ * Generate a unique token. The token is generated according to the following pattern. NOnceToken = time-stamp ":"
+ * Hex ( NONCE_DIGEST ( client-IP ":" time-stamp ":" private-key ) ).
*
* @param request HTTP Servlet request
*
@@ -698,7 +698,7 @@ public class DigestAuthenticator extends AuthenticatorBase {
}
}
String serverIpTimeKey = request.getRemoteAddr() + ":" + nonceTime + ":" + key;
- // Note: The digest used to generate the nonce is independent of the digest used for authentication/
+ // Note: The digest used to generate the nonce is independent of the digest used for authentication.
byte[] buffer =
ConcurrentMessageDigest.digest(NONCE_DIGEST, serverIpTimeKey.getBytes(StandardCharsets.ISO_8859_1));
String digestServerIpTimeKey = HexUtils.toHexString(buffer);
@@ -819,7 +819,7 @@ public class DigestAuthenticator extends AuthenticatorBase {
/**
* Get the timestamp when this nonce was created.
*
- * @return Timestamp in milliseconds
+ * @return Timestamp in nanoseconds (from {@link System#nanoTime()})
*/
public long getTimestamp() {
return timestamp;
diff --git a/java/org/apache/catalina/authenticator/SingleSignOnSessionKey.java b/java/org/apache/catalina/authenticator/SingleSignOnSessionKey.java
index 2e41d29ce5..0fb4c6a145 100644
--- a/java/org/apache/catalina/authenticator/SingleSignOnSessionKey.java
+++ b/java/org/apache/catalina/authenticator/SingleSignOnSessionKey.java
@@ -142,9 +142,6 @@ public class SingleSignOnSessionKey implements Serializable {
@Override
public String toString() {
- // Session ID is 32. Standard text is 36. Host could easily be 20+.
- // Context could be anything from 0 upwards. 128 seems like a reasonable
- // size to accommodate most cases without being too big.
return "Host: [" + hostName + "], Context: [" + contextName + "], SessionID: [" + sessionId + ']';
}
}
diff --git a/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java b/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java
index 4a5a2236ba..d68182860d 100644
--- a/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java
+++ b/java/org/apache/catalina/authenticator/SpnegoAuthenticator.java
@@ -263,8 +263,8 @@ public class SpnegoAuthenticator extends AuthenticatorBase {
Subject subject = lc.getSubject();
- // Assume the GSSContext is stateless
- // TODO: Confirm this assumption
+ // The GSSContext is stateless: a new GSSContext is created for each request and the server response token
+ // is sent back even when a 401 response is returned
final GSSManager manager = GSSManager.getInstance();
// IBM JDK only understands indefinite lifetime
final int credentialLifetime;
diff --git a/java/org/apache/catalina/authenticator/jaspic/CallbackHandlerImpl.java b/java/org/apache/catalina/authenticator/jaspic/CallbackHandlerImpl.java
index affb67533a..265cc01a58 100644
--- a/java/org/apache/catalina/authenticator/jaspic/CallbackHandlerImpl.java
+++ b/java/org/apache/catalina/authenticator/jaspic/CallbackHandlerImpl.java
@@ -111,7 +111,8 @@ public class CallbackHandlerImpl implements CallbackHandler, Contained {
if (name != null) {
// If the Principal has been cached in the session, just return it.
if (principal instanceof GenericPrincipal) {
- // Duplicates are unlikely and will be handled in AuthenticatorBase.getPrincipal()
+ // Duplicates are unlikely and are not merged; if present, AuthenticatorBase.getPrincipal()
+ // returns an arbitrary element of the set of credentials
subject.getPrivateCredentials().add(principal);
} else {
/*
diff --git a/java/org/apache/catalina/authenticator/jaspic/SimpleServerAuthConfig.java b/java/org/apache/catalina/authenticator/jaspic/SimpleServerAuthConfig.java
index 6df3994181..78a6c56f6a 100644
--- a/java/org/apache/catalina/authenticator/jaspic/SimpleServerAuthConfig.java
+++ b/java/org/apache/catalina/authenticator/jaspic/SimpleServerAuthConfig.java
@@ -94,7 +94,7 @@ public class SimpleServerAuthConfig implements ServerAuthConfig {
/**
* {@inheritDoc}
* <p>
- * Clears the cached ServerAuthConfig so it will be recreated on next use.
+ * Clears the cached ServerAuthContext so it will be recreated on next use.
*/
@Override
public void refresh() {
diff --git a/java/org/apache/catalina/connector/Connector.java b/java/org/apache/catalina/connector/Connector.java
index 05c2998a89..0013db3d21 100644
--- a/java/org/apache/catalina/connector/Connector.java
+++ b/java/org/apache/catalina/connector/Connector.java
@@ -626,7 +626,7 @@ public class Connector extends LifecycleMBeanBase {
/**
- * Set list of HTTP methods which should allow body parameter parsing. This defaults to <code>POST</code>.
+ * Set list of HTTP methods which should allow body parameter parsing. This defaults to <code>POST,QUERY</code>.
*
* @param methods Comma separated list of HTTP method names
*/
diff --git a/java/org/apache/catalina/connector/CoyoteOutputStream.java b/java/org/apache/catalina/connector/CoyoteOutputStream.java
index 6c4dfb6aaf..6a700be9d1 100644
--- a/java/org/apache/catalina/connector/CoyoteOutputStream.java
+++ b/java/org/apache/catalina/connector/CoyoteOutputStream.java
@@ -153,8 +153,7 @@ public class CoyoteOutputStream extends ServletOutputStream {
/**
- * Checks for concurrent writes which are not permitted. This object has no state information so the call chain is
- * CoyoteOutputStream->OutputBuffer->CoyoteResponse.
+ * Checks that the underlying output buffer is ready for writing when this OutputStream is in non-blocking mode.
*
* @return <code>true</code> if this OutputStream is currently in non-blocking mode.
*/
diff --git a/java/org/apache/catalina/connector/InputBuffer.java b/java/org/apache/catalina/connector/InputBuffer.java
index c84a38bdda..10fe74c300 100644
--- a/java/org/apache/catalina/connector/InputBuffer.java
+++ b/java/org/apache/catalina/connector/InputBuffer.java
@@ -100,7 +100,7 @@ public class InputBuffer extends Reader implements ByteChunk.ByteInputChannel, A
/**
- * State of the output buffer.
+ * State of the input buffer.
*/
private int state = 0;
@@ -130,7 +130,7 @@ public class InputBuffer extends Reader implements ByteChunk.ByteInputChannel, A
/**
- * Char buffer limit.
+ * Maximum buffer growth position, set by {@link #mark(int)} and used as a limit when growing the char buffer.
*/
private int readLimit;
diff --git a/java/org/apache/catalina/connector/Request.java b/java/org/apache/catalina/connector/Request.java
index 1b9dc53f10..82b9583b3f 100644
--- a/java/org/apache/catalina/connector/Request.java
+++ b/java/org/apache/catalina/connector/Request.java
@@ -135,8 +135,8 @@ public class Request implements HttpServletRequest {
* Create a new Request object associated with the given Connector.
*
* @param connector The Connector with which this Request object will always be associated. In normal usage this
- * must be non-null. In some test scenarios, it may be possible to use a null Connector
- * without triggering an NPE.
+ * must be non-null. Some methods require the Connector and will throw a
+ * <code>NullPointerException</code> if it is null.
* @param coyoteRequest The Coyote request with which this Request object will always be associated. In normal usage
* this must be non-null. In some test scenarios, it may be possible to use a null request
* without triggering an NPE.
@@ -404,7 +404,7 @@ public class Request implements HttpServletRequest {
/**
- * Local address
+ * Local name
*/
protected String localName = null;
diff --git a/java/org/apache/catalina/connector/RequestFacade.java b/java/org/apache/catalina/connector/RequestFacade.java
index 41b5eec8a8..6db43cfb9c 100644
--- a/java/org/apache/catalina/connector/RequestFacade.java
+++ b/java/org/apache/catalina/connector/RequestFacade.java
@@ -44,7 +44,7 @@ import jakarta.servlet.http.Part;
import org.apache.tomcat.util.res.StringManager;
/**
- * Facade class that wraps a Coyote request object. All methods are delegated to the wrapped request.
+ * Facade class that wraps a {@link Request} object. All methods are delegated to the wrapped request.
*/
public class RequestFacade implements HttpServletRequest {
diff --git a/java/org/apache/catalina/connector/ResponseFacade.java b/java/org/apache/catalina/connector/ResponseFacade.java
index 3affab22c0..606ee43484 100644
--- a/java/org/apache/catalina/connector/ResponseFacade.java
+++ b/java/org/apache/catalina/connector/ResponseFacade.java
@@ -31,7 +31,7 @@ import jakarta.servlet.http.HttpServletResponse;
import org.apache.tomcat.util.res.StringManager;
/**
- * Facade class that wraps a Coyote response object. All methods are delegated to the wrapped response.
+ * Facade class that wraps a {@link Response} object. All methods are delegated to the wrapped response.
*/
public class ResponseFacade implements HttpServletResponse {
diff --git a/java/org/apache/catalina/core/AccessLogAdapter.java b/java/org/apache/catalina/core/AccessLogAdapter.java
index 38a3f62aeb..8dc1666b4d 100644
--- a/java/org/apache/catalina/core/AccessLogAdapter.java
+++ b/java/org/apache/catalina/core/AccessLogAdapter.java
@@ -59,6 +59,13 @@ public class AccessLogAdapter implements AccessLog {
}
}
+ /**
+ * This method is a NO-OP. Each wrapped AccessLog instance maintains its own
+ * <code>requestAttributesEnabled</code> setting, so a single value cannot be applied to all of the wrapped
+ * instances.
+ *
+ * @param requestAttributesEnabled Ignored
+ */
@Override
public void setRequestAttributesEnabled(boolean requestAttributesEnabled) {
// NOOP
diff --git a/java/org/apache/catalina/core/ApplicationHttpRequest.java b/java/org/apache/catalina/core/ApplicationHttpRequest.java
index de9c20bebc..1523450b2f 100644
--- a/java/org/apache/catalina/core/ApplicationHttpRequest.java
+++ b/java/org/apache/catalina/core/ApplicationHttpRequest.java
@@ -51,10 +51,9 @@ import org.apache.tomcat.util.http.Parameters;
import org.apache.tomcat.util.res.StringManager;
/**
- * Wrapper around a <code>jakarta.servlet.http.HttpServletRequest</code> that transforms an application request object
- * (which might be the original one passed to a servlet, or might be based on the 2.3
- * <code>jakarta.servlet.http.HttpServletRequestWrapper</code> class) back into an internal
- * <code>org.apache.catalina.connector.Request</code>.
+ * Wrapper around a <code>jakarta.servlet.http.HttpServletRequest</code> that is used by the
+ * <code>RequestDispatcher</code> implementation to override the request attributes that are relevant to the current
+ * dispatch (e.g. the request URI, method and query string).
* <p>
* <strong>WARNING</strong>: Due to Java's lack of support for multiple inheritance, all of the logic in
* <code>ApplicationRequest</code> is duplicated in <code>ApplicationHttpRequest</code>. Make sure that you keep these
diff --git a/java/org/apache/catalina/core/ApplicationHttpResponse.java b/java/org/apache/catalina/core/ApplicationHttpResponse.java
index 68c27e4e40..5c186c8d3f 100644
--- a/java/org/apache/catalina/core/ApplicationHttpResponse.java
+++ b/java/org/apache/catalina/core/ApplicationHttpResponse.java
@@ -25,10 +25,9 @@ import jakarta.servlet.http.HttpServletResponseWrapper;
/**
- * Wrapper around a <code>jakarta.servlet.http.HttpServletResponse</code> that transforms an application response object
- * (which might be the original one passed to a servlet, or might be based on the 2.3
- * <code>jakarta.servlet.http.HttpServletResponseWrapper</code> class) back into an internal
- * <code>org.apache.catalina.connector.Response</code>.
+ * Wrapper around a <code>jakarta.servlet.http.HttpServletResponse</code> that is used by the
+ * <code>RequestDispatcher</code> implementation to suppress the response operations that are not permitted on an
+ * included response (e.g. changing the status code, headers or content length).
* <p>
* <strong>WARNING</strong>: Due to Java's lack of support for multiple inheritance, all of the logic in
* <code>ApplicationResponse</code> is duplicated in <code>ApplicationHttpResponse</code>. Make sure that you keep these
diff --git a/java/org/apache/catalina/core/ApplicationPart.java b/java/org/apache/catalina/core/ApplicationPart.java
index 04827c429e..95a7167b19 100644
--- a/java/org/apache/catalina/core/ApplicationPart.java
+++ b/java/org/apache/catalina/core/ApplicationPart.java
@@ -35,8 +35,9 @@ import org.apache.tomcat.util.http.fileupload.disk.DiskFileItem;
import org.apache.tomcat.util.http.parser.HttpParser;
/**
- * Adaptor to allow {@link FileItem} objects generated by the package renamed commons-upload to be used by the Servlet
- * 3.0 upload API that expects {@link Part}s.
+ * Adaptor to allow {@link FileItem} objects generated by the repackaged Apache Commons FileUpload package
+ * ({@code org.apache.tomcat.util.http.fileupload}) to be used by the Servlet 3.0 upload API that expects
+ * {@link Part}s.
*/
public class ApplicationPart implements Part {
diff --git a/java/org/apache/catalina/core/ApplicationSessionCookieConfig.java b/java/org/apache/catalina/core/ApplicationSessionCookieConfig.java
index a92dfa3611..dcf4185934 100644
--- a/java/org/apache/catalina/core/ApplicationSessionCookieConfig.java
+++ b/java/org/apache/catalina/core/ApplicationSessionCookieConfig.java
@@ -239,6 +239,8 @@ public class ApplicationSessionCookieConfig implements SessionCookieConfig {
for (Map.Entry<String,String> attribute : scc.getAttributes().entrySet()) {
switch (attribute.getKey()) {
case Constants.COOKIE_COMMENT_ATTR:
+ // Intentionally not applied. Since Servlet 6.0 the cookie comment is not supported (RFC 6265) so
+ // setComment()/getComment() are no-ops.
case Constants.COOKIE_DOMAIN_ATTR:
case Constants.COOKIE_MAX_AGE_ATTR:
case Constants.COOKIE_PATH_ATTR:
diff --git a/java/org/apache/catalina/core/AprLifecycleListener.java b/java/org/apache/catalina/core/AprLifecycleListener.java
index c8157ed53f..732f9dfe1a 100644
--- a/java/org/apache/catalina/core/AprLifecycleListener.java
+++ b/java/org/apache/catalina/core/AprLifecycleListener.java
@@ -199,7 +199,8 @@ public class AprLifecycleListener implements LifecycleListener {
/**
* Get a warning message if the installed Tomcat Native version is older than recommended.
- * This performs the same version check used during Tomcat startup.
+ * Unlike the version check performed during Tomcat startup, this only compares the installed version against the
+ * recommended version and does not enforce the required minimum version.
*
* @return a warning message if the installed version is outdated, or null if the version
* is acceptable or APR is not available
diff --git a/java/org/apache/catalina/core/AsyncContextImpl.java b/java/org/apache/catalina/core/AsyncContextImpl.java
index c22e1078c5..57e238d0ed 100644
--- a/java/org/apache/catalina/core/AsyncContextImpl.java
+++ b/java/org/apache/catalina/core/AsyncContextImpl.java
@@ -113,7 +113,7 @@ public class AsyncContextImpl implements AsyncContext, AsyncContextCallback {
*/
private final List<AsyncListenerWrapper> listeners = new CopyOnWriteArrayList<>();
private volatile Runnable dispatch = null;
- // Default of 30000 (30s) is set by the connector
+ // Set to the connector's async timeout when async processing starts
private long timeout = -1;
/*
diff --git a/java/org/apache/catalina/core/JniLifecycleListener.java b/java/org/apache/catalina/core/JniLifecycleListener.java
index b07d823018..ef1c238fec 100644
--- a/java/org/apache/catalina/core/JniLifecycleListener.java
+++ b/java/org/apache/catalina/core/JniLifecycleListener.java
@@ -24,7 +24,7 @@ import org.apache.juli.logging.LogFactory;
import org.apache.tomcat.util.res.StringManager;
/**
- * An implementation of LifeCycleListener that loads a native library into the JVM.
+ * An implementation of LifecycleListener that loads a native library into the JVM.
* <p>
* Native libraries are associated with the class loader of the class that loaded them, and the same library may not be
* loaded by more than one class loader. Due to that restriction, loading a native library from a Webapp's class loader
diff --git a/java/org/apache/catalina/core/StandardContext.java b/java/org/apache/catalina/core/StandardContext.java
index 7c5dc96077..49a1b4d003 100644
--- a/java/org/apache/catalina/core/StandardContext.java
+++ b/java/org/apache/catalina/core/StandardContext.java
@@ -5583,7 +5583,7 @@ public class StandardContext extends ContainerBase implements Context, Notificat
new MBeanNotificationInfo(new String[] { "j2ee.state.running" }, Notification.class.getName(),
"web application is running"),
new MBeanNotificationInfo(new String[] { "j2ee.state.stopping" }, Notification.class.getName(),
- "web application start to stopped"),
+ "web application is stopping"),
new MBeanNotificationInfo(new String[] { "j2ee.object.stopped" }, Notification.class.getName(),
"web application is stopped"),
new MBeanNotificationInfo(new String[] { "j2ee.object.deleted" }, Notification.class.getName(),
diff --git a/java/org/apache/catalina/core/StandardHost.java b/java/org/apache/catalina/core/StandardHost.java
index fbb55dfab9..86fff7b482 100644
--- a/java/org/apache/catalina/core/StandardHost.java
+++ b/java/org/apache/catalina/core/StandardHost.java
@@ -616,7 +616,7 @@ public class StandardHost extends ContainerBase implements Host {
/**
* Change the behavior of Servlet startup errors on web application starts.
*
- * @param failCtxIfServletStartFails <code>false</code> to ignore errors on Servlets which are stated when the web
+ * @param failCtxIfServletStartFails <code>false</code> to ignore errors on Servlets which are started when the web
* application starts
*/
public void setFailCtxIfServletStartFails(boolean failCtxIfServletStartFails) {
diff --git a/java/org/apache/catalina/core/StandardPipeline.java b/java/org/apache/catalina/core/StandardPipeline.java
index ca640db4ff..b25ac17690 100644
--- a/java/org/apache/catalina/core/StandardPipeline.java
+++ b/java/org/apache/catalina/core/StandardPipeline.java
@@ -40,9 +40,8 @@ import org.apache.tomcat.util.res.StringManager;
/**
* Standard implementation of a processing <b>Pipeline</b> that will invoke a series of Valves that have been configured
* to be called in order. This implementation can be used for any type of Container. <b>IMPLEMENTATION WARNING</b> -
- * This implementation assumes that no calls to <code>addValve()</code> or <code>removeValve</code> are allowed while a
- * request is currently being processed. Otherwise, the mechanism by which per-thread state is maintained will need to
- * be modified.
+ * This implementation assumes that no calls to <code>addValve()</code> or <code>removeValve()</code> are made while a
+ * request is currently being processed.
*/
public class StandardPipeline extends LifecycleBase implements Pipeline {
diff --git a/java/org/apache/catalina/core/StandardServer.java b/java/org/apache/catalina/core/StandardServer.java
index cb2961f2dd..3dca67b94d 100644
--- a/java/org/apache/catalina/core/StandardServer.java
+++ b/java/org/apache/catalina/core/StandardServer.java
@@ -422,7 +422,7 @@ public final class StandardServer extends LifecycleMBeanBase implements Server {
/**
- * Set the utility threads daemon flag. The default value is true.
+ * Set the utility threads daemon flag. The default value is false.
*
* @param utilityThreadsAsDaemon the new thread daemon flag
*/
diff --git a/java/org/apache/catalina/core/StandardWrapper.java b/java/org/apache/catalina/core/StandardWrapper.java
index d0ed7f9bac..8224acff03 100644
--- a/java/org/apache/catalina/core/StandardWrapper.java
+++ b/java/org/apache/catalina/core/StandardWrapper.java
@@ -910,7 +910,7 @@ public class StandardWrapper extends ContainerBase implements ServletConfig, Wra
}
unloading = true;
- // Loaf a while if the current instance is allocated. Use wait() to
+ // Wait a while if the current instance is allocated. Use wait() to
// release the lock while waiting to avoid blocking other threads.
if (countAllocated.get() > 0) {
int nRetries = 0;
@@ -1313,15 +1313,13 @@ public class StandardWrapper extends ContainerBase implements ServletConfig, Wra
public MBeanNotificationInfo[] getNotificationInfo() {
if (notificationInfo == null) {
notificationInfo = new MBeanNotificationInfo[] {
- new MBeanNotificationInfo(new String[] { "j2ee.object.created" }, Notification.class.getName(),
- "servlet is created"),
new MBeanNotificationInfo(new String[] { "j2ee.state.starting" }, Notification.class.getName(),
"servlet is starting"),
new MBeanNotificationInfo(new String[] { "j2ee.state.running" }, Notification.class.getName(),
"servlet is running"),
- new MBeanNotificationInfo(new String[] { "j2ee.state.stopped" }, Notification.class.getName(),
+ new MBeanNotificationInfo(new String[] { "j2ee.state.stopping" }, Notification.class.getName(),
"servlet is stopping"),
- new MBeanNotificationInfo(new String[] { "j2ee.object.stopped" }, Notification.class.getName(),
+ new MBeanNotificationInfo(new String[] { "j2ee.state.stopped" }, Notification.class.getName(),
"servlet is stopped"),
new MBeanNotificationInfo(new String[] { "j2ee.object.deleted" }, Notification.class.getName(),
"servlet is deleted") };
diff --git a/java/org/apache/catalina/core/StandardWrapperValve.java b/java/org/apache/catalina/core/StandardWrapperValve.java
index 4341c5e6ae..15c815e1af 100644
--- a/java/org/apache/catalina/core/StandardWrapperValve.java
+++ b/java/org/apache/catalina/core/StandardWrapperValve.java
@@ -87,7 +87,6 @@ final class StandardWrapperValve extends ValveBase {
// Initialize local variables we may need
boolean unavailable = false;
Throwable throwable = null;
- // This should be a Request attribute...
long t1 = System.nanoTime();
requestCount.increment();
StandardWrapper wrapper = (StandardWrapper) getContainer();
@@ -126,7 +125,6 @@ final class StandardWrapperValve extends ValveBase {
container.getLogger().error(sm.getString("standardWrapper.allocateException", wrapper.getName()), t);
throwable = t;
exception(request, response, t);
- // servlet = null; is set here
}
MessageBytes requestPathMB = request.getRequestPathMB();
diff --git a/java/org/apache/catalina/core/mbeans-descriptors.xml b/java/org/apache/catalina/core/mbeans-descriptors.xml
index ba1d0facb7..9d2e0eab50 100644
--- a/java/org/apache/catalina/core/mbeans-descriptors.xml
+++ b/java/org/apache/catalina/core/mbeans-descriptors.xml
@@ -366,12 +366,12 @@
</operation>
<operation name="addApplicationParameter"
- description="Add a new application parameter for this application."
- impact="ACTION"
- returnType="void">
- <parameter name="listener"
- description="Java class name of a listener class"
- type="java.lang.String"/>
+ description="Add a new application parameter for this application."
+ impact="ACTION"
+ returnType="void">
+ <parameter name="parameter"
+ description="Application parameter to add"
+ type="java.lang.String"/>
</operation>
<operation name="addChild"
@@ -537,15 +537,15 @@
</operation>
<operation name="findApplicationParameters"
- description="Return the set of application parameters for this application."
- impact="INFO"
- returnType="java.lang.String">
+ description="Return the set of application parameters for this application."
+ impact="INFO"
+ returnType="[Ljava.lang.String;">
</operation>
<operation name="findConstraints"
- description="Return the set of security constraints for this web application. If there are none, a zero-length array is returned."
- impact="INFO"
- returnType="java.lang.String">
+ description="Return the set of security constraints for this web application. If there are none, a zero-length array is returned."
+ impact="INFO"
+ returnType="[Ljava.lang.String;">
</operation>
<operation name="findContainerListenerNames"
@@ -579,12 +579,12 @@
</operation>
<operation name="findFilterDef"
- description="Return the filter definition for the specified filter name, if any; otherwise return null."
- impact="ACTION"
- returnType="java.lang.String">
- <parameter name="exceptionType"
- description="Exception type to look up"
- type="java.lang.String"/>
+ description="Return the filter definition for the specified filter name, if any; otherwise return null."
+ impact="ACTION"
+ returnType="java.lang.String">
+ <parameter name="name"
+ description="Filter name to look up"
+ type="java.lang.String"/>
</operation>
<operation name="findFilterDefs"
diff --git a/java/org/apache/catalina/deploy/NamingResourcesImpl.java b/java/org/apache/catalina/deploy/NamingResourcesImpl.java
index 850cc66acf..9d15e54666 100644
--- a/java/org/apache/catalina/deploy/NamingResourcesImpl.java
+++ b/java/org/apache/catalina/deploy/NamingResourcesImpl.java
@@ -61,7 +61,8 @@ import org.apache.tomcat.util.res.StringManager;
/**
- * Holds and manages the naming resources defined in the Jakarta EE Naming Context and their associated JNDI context.
+ * Holds and manages the naming resource descriptors. The associated JNDI context is created and maintained by
+ * NamingContextListener.
*/
public class NamingResourcesImpl extends LifecycleMBeanBase implements Serializable, NamingResources {
@@ -98,7 +99,7 @@ public class NamingResourcesImpl extends LifecycleMBeanBase implements Serializa
/**
- * Set of naming entries, keyed by name.
+ * Set of naming entry names.
*/
private final Set<String> entries = ConcurrentHashMap.newKeySet();
@@ -671,7 +672,7 @@ public class NamingResourcesImpl extends LifecycleMBeanBase implements Serializa
/**
- * Return the array of resource environment reference names for this web application.
+ * Return the array of resource environment references for this web application.
*
* @return the resource environment references, or a zero-length array if none
*/
@@ -992,7 +993,7 @@ public class NamingResourcesImpl extends LifecycleMBeanBase implements Serializa
/**
* Clean up a resource by calling the defined close method. For example, closing a database connection pool will
- * close it's open connections. This will happen on GC but that leaves db connections open that may cause issues.
+ * close its open connections. This will happen on GC but that leaves db connections open that may cause issues.
*
* @param resource The resource to close.
*/
diff --git a/java/org/apache/catalina/filters/AddDefaultCharsetFilter.java b/java/org/apache/catalina/filters/AddDefaultCharsetFilter.java
index 45a4e1040a..a4190eecbc 100644
--- a/java/org/apache/catalina/filters/AddDefaultCharsetFilter.java
+++ b/java/org/apache/catalina/filters/AddDefaultCharsetFilter.java
@@ -33,7 +33,7 @@ import org.apache.juli.logging.LogFactory;
/**
* Filter that explicitly sets the default character set for media subtypes of the "text" type to ISO-8859-1, or another
- * user defined character set. RFC2616 explicitly states that browsers must use ISO-8859-1 if no character set is
+ * user defined character set. RFC 9110 explicitly states that browsers must use ISO-8859-1 if no character set is
* defined for media with subtype "text". However, browsers may attempt to auto-detect the character set. This may be
* exploited by an attacker to perform an XSS attack. Internet Explorer has this behaviour by default. Other browsers
* have an option to enable it.<br>
diff --git a/java/org/apache/catalina/filters/CorsFilter.java b/java/org/apache/catalina/filters/CorsFilter.java
index 52be34ee19..d42e07c252 100644
--- a/java/org/apache/catalina/filters/CorsFilter.java
+++ b/java/org/apache/catalina/filters/CorsFilter.java
@@ -452,8 +452,8 @@ public class CorsFilter extends GenericFilter {
* <li><b>cors.isCorsRequest:</b> Flag to determine if request is a CORS request. Set to <code>true</code> if CORS
* request; <code>false</code> otherwise.</li>
* <li><b>cors.request.origin:</b> The Origin URL.</li>
- * <li><b>cors.request.type:</b> Type of request. Values: <code>simple</code> or <code>preflight</code> or
- * <code>not_cors</code> or <code>invalid_cors</code></li>
+ * <li><b>cors.request.type:</b> Type of request. Values: <code>simple</code> or <code>actual</code> or
+ * <code>preflight</code> or <code>not_cors</code> or <code>invalid_cors</code></li>
* <li><b>cors.request.headers:</b> Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight
* request.</li>
* </ul>
@@ -504,7 +504,7 @@ public class CorsFilter extends GenericFilter {
* Joins elements of {@link Set} into a string, where each element is separated by the provided separator.
*
* @param elements The {@link Set} containing elements to join together.
- * @param joinSeparator The character to be used for separating elements.
+ * @param joinSeparator The string to be used for separating elements.
*
* @return The joined {@link String}; <code>null</code> if elements {@link Set} is null.
*/
diff --git a/java/org/apache/catalina/filters/CsrfPreventionFilter.java b/java/org/apache/catalina/filters/CsrfPreventionFilter.java
index 2b0ee326d7..1dcdca63f2 100644
--- a/java/org/apache/catalina/filters/CsrfPreventionFilter.java
+++ b/java/org/apache/catalina/filters/CsrfPreventionFilter.java
@@ -467,9 +467,10 @@ public class CsrfPreventionFilter extends CsrfPreventionFilterBase {
}
/**
- * Check to see if the request and path should be enforced or only observed and reported. Note that the
- * <code>requestedPath</code> parameter is purely a performance optimization to avoid calling
- * {@link #getRequestedPath(HttpServletRequest)} multiple times.
+ * Check to see if the request and path should be enforced or only observed and reported. The
+ * <code>requestedPath</code> parameter can be used as a performance optimization to avoid calling
+ * {@link #getRequestedPath(HttpServletRequest)} multiple times. The default implementation only considers
+ * {@link #isEnforce()} and ignores both parameters.
*
* @param req The request.
* @param requestedPath The path of the request being evaluated.
diff --git a/java/org/apache/catalina/filters/RemoteIpFilter.java b/java/org/apache/catalina/filters/RemoteIpFilter.java
index 71a28e4725..5c9798324e 100644
--- a/java/org/apache/catalina/filters/RemoteIpFilter.java
+++ b/java/org/apache/catalina/filters/RemoteIpFilter.java
@@ -105,7 +105,7 @@ import org.apache.tomcat.util.res.StringManager;
* the requesting client</td>
* <td>RemoteIPHeader</td>
* <td>Compliant http header name</td>
- * <td>x-forwarded-for</td>
+ * <td>X-Forwarded-For</td>
* </tr>
* <tr>
* <td>internalProxies</td>
@@ -122,7 +122,7 @@ import org.apache.tomcat.util.res.StringManager;
* the incoming <code>remoteIpHeader</code></td>
* <td>RemoteIPProxiesHeader</td>
* <td>Compliant http header name</td>
- * <td>x-forwarded-by</td>
+ * <td>X-Forwarded-By</td>
* </tr>
* <tr>
* <td>trustedProxies</td>
@@ -135,7 +135,8 @@ import org.apache.tomcat.util.res.StringManager;
* </tr>
* <tr>
* <td>protocolHeader</td>
- * <td>Name of the http header read by this servlet filter that holds the flag that this request</td>
+ * <td>Name of the http header read by this servlet filter that holds the protocol the client used to connect to the
+ * proxy</td>
* <td>N/A</td>
* <td>Compliant http header name like <code>X-Forwarded-Proto</code>, <code>X-Forwarded-Ssl</code> or
* <code>Front-End-Https</code></td>
@@ -193,7 +194,7 @@ import org.apache.tomcat.util.res.StringManager;
* <param-value>x-forwarded-for</param-value>
* </init-param>
* <init-param>
- * <param-name>remoteIpProxiesHeader</param-name>
+ * <param-name>proxiesHeader</param-name>
* <param-value>x-forwarded-by</param-value>
* </init-param>
* <init-param>
@@ -251,8 +252,7 @@ import org.apache.tomcat.util.res.StringManager;
* <td>443</td>
* </tr>
* </table>
- * Note : <code>x-forwarded-by</code> header is null because only internal proxies as been traversed by the request.
- * <code>x-forwarded-by</code> is null because all the proxies are trusted or internal.
+ * Note : <code>x-forwarded-by</code> header is null because only internal proxies have been traversed by the request.
* <hr>
* <p>
* <strong>Sample with trusted proxies</strong>
@@ -274,7 +274,7 @@ import org.apache.tomcat.util.res.StringManager;
* <param-value>x-forwarded-for</param-value>
* </init-param>
* <init-param>
- * <param-name>remoteIpProxiesHeader</param-name>
+ * <param-name>proxiesHeader</param-name>
* <param-value>x-forwarded-by</param-value>
* </init-param>
* <init-param>
@@ -314,8 +314,7 @@ import org.apache.tomcat.util.res.StringManager;
* </table>
* <p>
* Note : <code>proxy1</code> and <code>proxy2</code> are both trusted proxies that come in <code>x-forwarded-for</code>
- * header, they both are migrated in <code>x-forwarded-by</code> header. <code>x-forwarded-by</code> is null because all
- * the proxies are trusted or internal.
+ * header, they both are migrated in <code>x-forwarded-by</code> header.
* </p>
* <hr>
* <p>
@@ -338,7 +337,7 @@ import org.apache.tomcat.util.res.StringManager;
* <param-value>x-forwarded-for</param-value>
* </init-param>
* <init-param>
- * <param-name>remoteIpProxiesHeader</param-name>
+ * <param-name>proxiesHeader</param-name>
* <param-value>x-forwarded-by</param-value>
* </init-param>
* <init-param>
@@ -379,8 +378,7 @@ import org.apache.tomcat.util.res.StringManager;
* <p>
* Note : <code>proxy1</code> and <code>proxy2</code> are both trusted proxies that come in <code>x-forwarded-for</code>
* header, they both are migrated in <code>x-forwarded-by</code> header. As <code>192.168.0.10</code> is an internal
- * proxy, it does not appear in <code>x-forwarded-by</code>. <code>x-forwarded-by</code> is null because all the proxies
- * are trusted or internal.
+ * proxy, it does not appear in <code>x-forwarded-by</code>.
* </p>
* <hr>
* <p>
@@ -403,7 +401,7 @@ import org.apache.tomcat.util.res.StringManager;
* <param-value>x-forwarded-for</param-value>
* </init-param>
* <init-param>
- * <param-name>remoteIpProxiesHeader</param-name>
+ * <param-name>proxiesHeader</param-name>
* <param-value>x-forwarded-by</param-value>
* </init-param>
* <init-param>
@@ -442,7 +440,7 @@ import org.apache.tomcat.util.res.StringManager;
* </tr>
* </table>
* <p>
- * Note : <code>x-forwarded-by</code> holds the trusted proxy <code>proxy1</code>. <code>x-forwarded-by</code> holds
+ * Note : <code>x-forwarded-by</code> holds the trusted proxy <code>proxy1</code>. <code>x-forwarded-for</code> holds
* <code>140.211.11.130</code> because <code>untrusted-proxy</code> is not trusted and thus, we cannot trust that
* <code>untrusted-proxy</code> is the actual remote ip. <code>request.remoteAddr</code> is <code>untrusted-proxy</code>
* that is an IP verified by <code>proxy1</code>.
diff --git a/java/org/apache/catalina/filters/RequestFilter.java b/java/org/apache/catalina/filters/RequestFilter.java
index ea829651c5..506566b51f 100644
--- a/java/org/apache/catalina/filters/RequestFilter.java
+++ b/java/org/apache/catalina/filters/RequestFilter.java
@@ -43,7 +43,8 @@ import jakarta.servlet.http.HttpServletResponse;
* this request will be allowed to pass through to the next filter in the current pipeline.</li>
* <li>If a deny expression was specified but no allow expression, allow this request to pass through (because none of
* the deny expressions matched it).</li>
- * <li>The request will be rejected with a "Forbidden" HTTP response.</li>
+ * <li>Otherwise (an allow expression was configured but did not match, or no expressions were configured at all), the
+ * request will be rejected with a "Forbidden" HTTP response.</li>
* </ul>
*/
public abstract class RequestFilter extends FilterBase {
diff --git a/java/org/apache/catalina/ha/CatalinaCluster.java b/java/org/apache/catalina/ha/CatalinaCluster.java
index d693fa2817..908b4002bb 100644
--- a/java/org/apache/catalina/ha/CatalinaCluster.java
+++ b/java/org/apache/catalina/ha/CatalinaCluster.java
@@ -76,7 +76,7 @@ public interface CatalinaCluster extends Cluster {
Member getLocalMember();
/**
- * Add cluster valve. Cluster Valves are only add to container when cluster is started.
+ * Add a cluster valve. Cluster valves are only added to the container when the cluster is started.
*
* @param valve The new cluster Valve.
*/
diff --git a/java/org/apache/catalina/ha/ClusterDeployer.java b/java/org/apache/catalina/ha/ClusterDeployer.java
index aacf7d5c16..5dc15cd751 100644
--- a/java/org/apache/catalina/ha/ClusterDeployer.java
+++ b/java/org/apache/catalina/ha/ClusterDeployer.java
@@ -42,11 +42,8 @@ public interface ClusterDeployer extends ChannelListener {
void stop() throws LifecycleException;
/**
- * Install a new web application, whose web application archive is at the specified URL, into this container and all
+ * Install a new web application, whose web application archive is the specified file, into this container and all
* the other members of the cluster with the specified context name.
- * <p>
- * If this application is successfully installed locally, a ContainerEvent of type <code>INSTALL_EVENT</code> will
- * be sent to all registered listeners, with the newly created <code>Context</code> as an argument.
*
* @param contextName The context name to which this application should be installed (must be unique)
* @param webapp A WAR file or unpacked directory structure containing the web application to be installed
@@ -59,10 +56,8 @@ public interface ClusterDeployer extends ChannelListener {
void install(String contextName, File webapp) throws IOException;
/**
- * Remove an existing web application, attached to the specified context name. If this application is successfully
- * removed, a ContainerEvent of type <code>REMOVE_EVENT</code> will be sent to all registered listeners, with the
- * removed <code>Context</code> as an argument. Deletes the web application war file and/or directory if they exist
- * in the Host's appBase.
+ * Remove an existing web application, attached to the specified context name. Deletes the web application war file
+ * and/or directory if they exist in the Host's appBase.
*
* @param contextName The context name of the application to be removed
* @param undeploy boolean flag to remove web application from server
diff --git a/java/org/apache/catalina/ha/ClusterManager.java b/java/org/apache/catalina/ha/ClusterManager.java
index f4fb536442..c7fd0d3f88 100644
--- a/java/org/apache/catalina/ha/ClusterManager.java
+++ b/java/org/apache/catalina/ha/ClusterManager.java
@@ -57,11 +57,9 @@ public interface ClusterManager extends Manager {
String[] getInvalidatedSessions();
/**
- * Return the name of the manager, at host /context name and at engine hostname+/context.
+ * Return the name of the manager.
*
- * @return String
- *
- * @since 5.5.10
+ * @return the name of the manager
*/
String getName();
@@ -69,8 +67,6 @@ public interface ClusterManager extends Manager {
* Set the name of the manager, at host /context name and at engine hostname+/context
*
* @param name The manager name
- *
- * @since 5.5.10
*/
void setName(String name);
diff --git a/java/org/apache/catalina/ha/authenticator/ClusterSingleSignOn.java b/java/org/apache/catalina/ha/authenticator/ClusterSingleSignOn.java
index 22defbf66a..a322ad6132 100644
--- a/java/org/apache/catalina/ha/authenticator/ClusterSingleSignOn.java
+++ b/java/org/apache/catalina/ha/authenticator/ClusterSingleSignOn.java
@@ -36,7 +36,8 @@ import org.apache.tomcat.util.res.StringManager;
/**
* A <strong>Valve</strong> that supports a "single sign on" user experience on each node of a cluster, where the
* security identity of a user who successfully authenticates to one web application is propagated to other web
- * applications and to other nodes cluster in the same security domain. For successful use, the following requirements
+ * applications and to other nodes in the cluster in the same security domain. For successful use, the following
+ * requirements
* must be met:
* <ul>
* <li>This Valve must be configured on the Container that represents a virtual host (typically an implementation of
diff --git a/java/org/apache/catalina/ha/backend/HeartbeatListener.java b/java/org/apache/catalina/ha/backend/HeartbeatListener.java
index b418e80be2..0d3384ba14 100644
--- a/java/org/apache/catalina/ha/backend/HeartbeatListener.java
+++ b/java/org/apache/catalina/ha/backend/HeartbeatListener.java
@@ -25,7 +25,7 @@ import org.apache.tomcat.util.res.StringManager;
/**
* Lifecycle listener that provides heartbeat information to mod_heartbeat for Apache HTTP Server.
- * Message format: "v=%u&ready=%u&busy=%u"
+ * Message format: "v=1&ready=%u&busy=%u&port=%u"
*/
public class HeartbeatListener implements LifecycleListener {
@@ -177,10 +177,11 @@ public class HeartbeatListener implements LifecycleListener {
}
/**
- * Set the list of Proxies that send is requests, when not empty it toggles the multi to off. A SetHandler heartbeat
- * must be existing in httpd.conf.
+ * Set the list of Proxies that heartbeat requests are sent to. When set, the TCP sender is used instead of the
+ * multicast sender, starting with the first heartbeat sent; the choice is not re-evaluated if the list is
+ * changed later. A SetHandler heartbeat must exist in httpd.conf.
*
- * @param proxyList the list of proxy, format "address:port,address:port".
+ * @param proxyList the list of proxies, format "address:port,address:port".
*/
public void setProxyList(String proxyList) {
this.proxyList = proxyList;
diff --git a/java/org/apache/catalina/ha/context/ReplicatedContext.java b/java/org/apache/catalina/ha/context/ReplicatedContext.java
index bc7f28913c..a0e02ea31e 100644
--- a/java/org/apache/catalina/ha/context/ReplicatedContext.java
+++ b/java/org/apache/catalina/ha/context/ReplicatedContext.java
@@ -106,7 +106,8 @@ public class ReplicatedContext extends StandardContext implements MapOwner {
/**
- * Set the options for sending map updates.
+ * Set the options for sending map updates. The value is only used when
+ * the context (re)starts.
*
* @param mapSendOptions the send options
*/
diff --git a/java/org/apache/catalina/ha/deploy/FarmWarDeployer.java b/java/org/apache/catalina/ha/deploy/FarmWarDeployer.java
index ccf8fbde80..9772b2708d 100644
--- a/java/org/apache/catalina/ha/deploy/FarmWarDeployer.java
+++ b/java/org/apache/catalina/ha/deploy/FarmWarDeployer.java
@@ -50,7 +50,7 @@ import org.apache.tomcat.util.res.StringManager;
* <ul>
* <li>watchDir - the directory where we watch for changes</li>
* <li>deployDir - the directory where we install applications</li>
- * <li>tempDir - a temporaryDirectory to store binary data when downloading a war from the cluster</li>
+ * <li>tempDir - a temporary directory to store binary data when downloading a war from the cluster</li>
* </ul>
* Currently we only support deployment of WAR files since they are easier to send across the wire.
*/
@@ -336,7 +336,6 @@ public class FarmWarDeployer extends ClusterListener implements ClusterDeployer,
* @param webapp A WAR file or unpacked directory structure containing the web application to be installed
*
* @exception IllegalArgumentException if the specified context name is malformed
- * @exception IllegalStateException if the specified context name is already deployed
* @exception IOException if an input/output error was encountered during installation
*/
@Override
@@ -727,7 +726,7 @@ public class FarmWarDeployer extends ClusterListener implements ClusterDeployer,
/**
* Set the watcher checks frequency.
*
- * @param processExpiresFrequency the new manager checks frequency
+ * @param processExpiresFrequency the new watcher checks frequency
*/
public void setProcessDeployFrequency(int processExpiresFrequency) {
diff --git a/java/org/apache/catalina/ha/deploy/FileMessageFactory.java b/java/org/apache/catalina/ha/deploy/FileMessageFactory.java
index 8fecb7949d..a0aa8bc2ba 100644
--- a/java/org/apache/catalina/ha/deploy/FileMessageFactory.java
+++ b/java/org/apache/catalina/ha/deploy/FileMessageFactory.java
@@ -36,7 +36,7 @@ import org.apache.tomcat.util.res.StringManager;
* The factory can be used as a reader or writer but not both at the same time. When done reading or writing the factory
* will close the input or output streams and mark the factory as closed. It is not possible to use it after that. <BR>
* To force a cleanup, call cleanup() from the calling object. <BR>
- * This class is not thread safe.
+ * The read path is not thread safe. The write path is synchronized.
*/
public class FileMessageFactory {
/*--Static Variables----------------------------------------*/
diff --git a/java/org/apache/catalina/ha/deploy/WarWatcher.java b/java/org/apache/catalina/ha/deploy/WarWatcher.java
index 9a6ae19440..c0145b7cb5 100644
--- a/java/org/apache/catalina/ha/deploy/WarWatcher.java
+++ b/java/org/apache/catalina/ha/deploy/WarWatcher.java
@@ -27,7 +27,7 @@ import org.apache.juli.logging.LogFactory;
import org.apache.tomcat.util.res.StringManager;
/**
- * The <b>WarWatcher </b> watches the deployDir for changes made to the directory (adding new WAR files->deploy or
+ * The <b>WarWatcher </b> watches the watchDir for changes made to the directory (adding new WAR files->deploy or
* remove WAR files->undeploy) and notifies a listener of the changes made.
*/
public class WarWatcher {
diff --git a/java/org/apache/catalina/ha/session/DeltaManager.java b/java/org/apache/catalina/ha/session/DeltaManager.java
index f6a8269735..842c586da6 100644
--- a/java/org/apache/catalina/ha/session/DeltaManager.java
+++ b/java/org/apache/catalina/ha/session/DeltaManager.java
@@ -45,8 +45,7 @@ import org.apache.tomcat.util.res.StringManager;
* The DeltaManager manages replicated sessions by only replicating the deltas in data. For applications written to
* handle this, the DeltaManager is the optimal way of replicating data.
* <p>
- * This code is almost identical to StandardManager with a difference in how it persists sessions and some modifications
- * to it.
+ * This manager extends {@link ClusterManagerBase} and does not persist sessions.
* <p>
* <b>IMPLEMENTATION NOTE </b>: Correct behavior of session storing and reloading depends upon external calls to the
* <code>start()</code> and <code>stop()</code> methods of this class at the correct times.
diff --git a/java/org/apache/catalina/ha/session/DeltaRequest.java b/java/org/apache/catalina/ha/session/DeltaRequest.java
index 520f99a67c..5a04057888 100644
--- a/java/org/apache/catalina/ha/session/DeltaRequest.java
+++ b/java/org/apache/catalina/ha/session/DeltaRequest.java
@@ -195,7 +195,8 @@ public class DeltaRequest implements Externalizable {
}
/**
- * Only support principals from type {@link GenericPrincipal GenericPrincipal}
+ * Only support principals from type {@link GenericPrincipal GenericPrincipal}. Any other principal type is logged
+ * as an error and recorded as a {@code null} value, which removes the principal on the replica nodes.
*
* @param p Session principal
*
diff --git a/java/org/apache/catalina/ha/session/JvmRouteBinderValve.java b/java/org/apache/catalina/ha/session/JvmRouteBinderValve.java
index b2a7206f18..ea3f4e12a3 100644
--- a/java/org/apache/catalina/ha/session/JvmRouteBinderValve.java
+++ b/java/org/apache/catalina/ha/session/JvmRouteBinderValve.java
@@ -115,7 +115,7 @@ public class JvmRouteBinderValve extends ValveBase implements ClusterValve {
}
/**
- * get name of failed request session attribute
+ * set name of failed request session attribute
*
* @param sessionIdAttribute The sessionIdAttribute to set.
*/
diff --git a/java/org/apache/catalina/ha/session/SessionMessageImpl.java b/java/org/apache/catalina/ha/session/SessionMessageImpl.java
index afedd8447f..ce20e95af1 100644
--- a/java/org/apache/catalina/ha/session/SessionMessageImpl.java
+++ b/java/org/apache/catalina/ha/session/SessionMessageImpl.java
@@ -82,7 +82,7 @@ public class SessionMessageImpl extends ClusterMessageBase implements SessionMes
* send that context manager does not exist after GET_ALL_SESSION received from this sender.<BR>
*
* @param contextName - the name of the context (application
- * @param eventtype - one of the 8 event type defined in this class
+ * @param eventtype - one of the 9 event types defined in this class
* @param session - the serialized byte array of the session itself
* @param sessionID - the id that identifies this session
* @param uniqueID - the id that identifies this message
diff --git a/java/org/apache/catalina/ha/tcp/ReplicationValve.java b/java/org/apache/catalina/ha/tcp/ReplicationValve.java
index d35955da50..45fe311b46 100644
--- a/java/org/apache/catalina/ha/tcp/ReplicationValve.java
+++ b/java/org/apache/catalina/ha/tcp/ReplicationValve.java
@@ -86,7 +86,7 @@ public class ReplicationValve extends ValveBase implements ClusterValve {
*/
protected LongAdder totalSendTime = new LongAdder();
/**
- * Total number of requests.
+ * Time (in milliseconds) of the last replication send.
*/
protected AtomicLong lastSendTime = new AtomicLong();
/**
diff --git a/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java b/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java
index 1ca655f6f7..7dfd70a47c 100644
--- a/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java
+++ b/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java
@@ -174,7 +174,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
protected final List<ClusterListener> clusterListeners = new CopyOnWriteArrayList<>();
/**
- * Comment for <code>notifyLifecycleListenerOnFailure</code>
+ * Whether to notify the lifecycle listeners about message transfer failures.
*/
private boolean notifyLifecycleListenerOnFailure = false;
diff --git a/java/org/apache/catalina/ha/tcp/mbeans-descriptors.xml b/java/org/apache/catalina/ha/tcp/mbeans-descriptors.xml
index 40a019c198..49bf9fa6ed 100644
--- a/java/org/apache/catalina/ha/tcp/mbeans-descriptors.xml
+++ b/java/org/apache/catalina/ha/tcp/mbeans-descriptors.xml
@@ -28,7 +28,7 @@
<attribute
name="channelSendOptions"
description="This sets channel behaviour on sent messages."
- type="java.lang.String"/>
+ type="int"/>
<attribute
name="channelSendOptionsName"
description="channelSendOptions name."
@@ -37,7 +37,7 @@
<attribute
name="channelStartOptions"
description="This sets channel start behaviour."
- type="java.lang.String"/>
+ type="int"/>
<attribute
name="clusterName"
description="name of cluster"
diff --git a/java/org/apache/catalina/loader/WebappClassLoaderBase.java b/java/org/apache/catalina/loader/WebappClassLoaderBase.java
index 4f7ebb62b6..b65cae7f37 100644
--- a/java/org/apache/catalina/loader/WebappClassLoaderBase.java
+++ b/java/org/apache/catalina/loader/WebappClassLoaderBase.java
@@ -249,10 +249,10 @@ public abstract class WebappClassLoaderBase extends URLClassLoader
/**
* Should Tomcat attempt to terminate threads that have been started by the web application? Stopping threads is
- * performed via the deprecated (for good reason) <code>Thread.stop()</code> method and is likely to result in
- * instability. As such, enabling this should be viewed as an option of last resort in a development environment and
- * is not recommended in a production environment. If not specified, the default value of <code>false</code> will be
- * used.
+ * performed by interrupting the threads, after shutting down the associated executor when the thread was started
+ * via one, and is likely to result in instability. As such, enabling this should be viewed as an option of last
+ * resort in a development environment and is not recommended in a production environment. If not specified, the
+ * default value of <code>false</code> will be used.
*/
private boolean clearReferencesStopThreads = false;
@@ -1314,8 +1314,7 @@ public abstract class WebappClassLoaderBase extends URLClassLoader
}
/**
- * Get the Permissions for a CodeSource. If this instance of WebappClassLoaderBase is for a web application context,
- * add read FilePermission for the appropriate resources.
+ * Get the Permissions for a CodeSource. This implementation always returns <code>null</code>.
*
* @param codeSource where the code was loaded from
*
diff --git a/java/org/apache/catalina/manager/HTMLManagerServlet.java b/java/org/apache/catalina/manager/HTMLManagerServlet.java
index ca13dc2c12..6cbb793fa6 100644
--- a/java/org/apache/catalina/manager/HTMLManagerServlet.java
+++ b/java/org/apache/catalina/manager/HTMLManagerServlet.java
@@ -62,7 +62,7 @@ import org.apache.tomcat.util.security.Escape;
* interface which makes it easier to administrate.
* <p>
* However if you use a software that parses the output of <code>ManagerServlet</code> you won't be able to upgrade to
- * this Servlet since the output are not in the same format ar from <code>ManagerServlet</code>
+ * this Servlet since the output is not in the same format as <code>ManagerServlet</code>
*
* @see ManagerServlet
*/
diff --git a/java/org/apache/catalina/manager/JspHelper.java b/java/org/apache/catalina/manager/JspHelper.java
index 7c661d75c9..d0abf01e29 100644
--- a/java/org/apache/catalina/manager/JspHelper.java
+++ b/java/org/apache/catalina/manager/JspHelper.java
@@ -36,7 +36,7 @@ public class JspHelper {
private static final String DATE_TIME_FORMAT = "yyyy-MM-dd HH:mm:ss";
/**
- * Public constructor, so that this class can be considered a JavaBean
+ * Private constructor, as this is a static utility class.
*/
private JspHelper() {
super();
diff --git a/java/org/apache/catalina/manager/ManagerServlet.java b/java/org/apache/catalina/manager/ManagerServlet.java
index a91e875c0d..953b5f6a6c 100644
--- a/java/org/apache/catalina/manager/ManagerServlet.java
+++ b/java/org/apache/catalina/manager/ManagerServlet.java
@@ -96,6 +96,9 @@ import org.apache.tomcat.util.security.Escape;
* attribute with the contents of the web application archive found at <code>{war-url}</code>.</li>
* <li><b>/deploy?path=/xxx&war={war-url}</b> - Install and start a new web application attached to context path
* <code>/xxx</code>, based on the contents of the web application archive found at the specified URL.</li>
+ * <li><b>/deploy?path=/xxx&tag={tag}</b> - Install and start a new web application attached to context path
+ * <code>/xxx</code>, based on the web application archive named <code>{baseName}.war</code> in the <code>{tag}</code>
+ * sub-directory of the temporary directory of this web application.</li>
* <li><b>/list</b> - List the context paths of all currently installed web applications for this virtual host. Each
* context will be listed with the following format <code>path:status:sessions</code>. Where path is the context path.
* Status is either running or stopped. Sessions is the number of active Sessions.</li>
@@ -103,13 +106,21 @@ import org.apache.tomcat.util.security.Escape;
* <li><b>/resources?type=xxxx</b> - Enumerate the available global JNDI resources, optionally limited to those of the
* specified type (fully qualified Java class name), if available.</li>
* <li><b>/serverinfo</b> - Display system OS and JVM properties.
- * <li><b>/sessions</b> - Deprecated. Use expire.
+ * <li><b>/sessions?path=/xxx</b> - Deprecated alias for <b>/expire?path=/xxx</b>.
* <li><b>/expire?path=/xxx</b> - List session idle time information about the web application attached to context path
* <code>/xxx</code> for this virtual host.</li>
* <li><b>/expire?path=/xxx&idle=mm</b> - Expire sessions for the context path <code>/xxx</code> which were idle for
* at least mm minutes.</li>
+ * <li><b>/findleaks</b> - List the context paths of the web applications of this virtual host for which memory leaks
+ * have been detected.</li>
* <li><b>/sslConnectorCiphers</b> - Display diagnostic info on SSL/TLS ciphers that are currently configured for each
- * connector.
+ * connector.</li>
+ * <li><b>/sslConnectorCerts</b> - Display diagnostic info on the SSL/TLS server certificates that are currently
+ * configured for each connector.</li>
+ * <li><b>/sslConnectorTrustedCerts</b> - Display diagnostic info on the SSL/TLS trusted certificates that are currently
+ * configured for each connector.</li>
+ * <li><b>/sslReload</b> - Reload the SSL/TLS configuration of all SSL connectors, or of the single connector with the
+ * specified <code>tlsHostName</code> if that parameter is provided.</li>
* <li><b>/start?path=/xxx</b> - Start the web application attached to context path <code>/xxx</code> for this virtual
* host.</li>
* <li><b>/stop?path=/xxx</b> - Stop the web application attached to context path <code>/xxx</code> for this virtual
@@ -126,6 +137,10 @@ import org.apache.tomcat.util.security.Escape;
* Host.</li>
* </ul>
* <p>
+ * A <code>PUT</code> request to <b>/deploy?path=/xxx</b> deploys a web application attached to context path
+ * <code>/xxx</code> using the web application archive provided in the request body.
+ * </p>
+ * <p>
* Use <code>path=/</code> for the ROOT context.
* </p>
* <p>
@@ -136,6 +151,8 @@ import org.apache.tomcat.util.security.Escape;
* <li><b>file:/absolute/path/to/a/directory</b> - You can specify the absolute path of a directory that contains the
* unpacked version of a web application. This directory will be attached to the context path you specify without any
* changes.</li>
+ * <li><b>file:/absolute/path/to/a/file.war</b> - You can specify the absolute path of a web application archive. This
+ * web application will be attached to the context path you specify.</li>
* </ul>
* <p>
* <b>NOTE</b> - Attempting to reload or remove the application containing this servlet itself will not succeed.
@@ -1212,7 +1229,8 @@ public class ManagerServlet extends HttpServlet implements ContainerServlet {
/**
* Session information for the web application at the specified context path. Displays a profile of session
- * thisAccessedTime listing number of sessions for each 10 minute interval up to 10 hours.
+ * thisAccessedTime as a histogram. The histogram covers the context default session timeout, divided into up to 60
+ * intervals.
*
* @param writer Writer to render to
* @param cn Name of the application to list session information for
diff --git a/java/org/apache/catalina/manager/StatusManagerServlet.java b/java/org/apache/catalina/manager/StatusManagerServlet.java
index 1d3623e029..93b8945b88 100644
--- a/java/org/apache/catalina/manager/StatusManagerServlet.java
+++ b/java/org/apache/catalina/manager/StatusManagerServlet.java
@@ -44,7 +44,9 @@ import org.apache.tomcat.util.modeler.Registry;
import org.apache.tomcat.util.res.StringManager;
/**
- * This servlet will display a complete status of the HTTP/1.1 connector.
+ * This servlet will display the status of the server, including JVM memory pools, connector thread pools and, for the
+ * <code>/all</code> path, the status of each deployed web application. The status is rendered in HTML, XML (when the
+ * <code>XML</code> request parameter is set) or JSON (when the <code>JSON</code> request parameter is set).
*/
public class StatusManagerServlet extends HttpServlet implements NotificationListener {
diff --git a/java/org/apache/catalina/manager/host/HTMLHostManagerServlet.java b/java/org/apache/catalina/manager/host/HTMLHostManagerServlet.java
index 23e4594bc8..41debd06e2 100644
--- a/java/org/apache/catalina/manager/host/HTMLHostManagerServlet.java
+++ b/java/org/apache/catalina/manager/host/HTMLHostManagerServlet.java
@@ -226,8 +226,7 @@ public class HTMLHostManagerServlet extends HostManagerServlet {
/**
- * Render an HTML list of the currently active Contexts in our virtual host, and memory and server status
- * information.
+ * Render an HTML list of the currently active virtual hosts in our engine, and server status information.
*
* @param request The request
* @param response The response
diff --git a/java/org/apache/catalina/manager/host/HostManagerServlet.java b/java/org/apache/catalina/manager/host/HostManagerServlet.java
index 0a7bfab5af..4111306215 100644
--- a/java/org/apache/catalina/manager/host/HostManagerServlet.java
+++ b/java/org/apache/catalina/manager/host/HostManagerServlet.java
@@ -77,7 +77,7 @@ import org.apache.tomcat.util.res.StringManager;
* The following servlet initialization parameters are recognized:
* <ul>
* <li><b>debug</b> - The debugging detail level that controls the amount of information that is logged by this servlet.
- * Default is zero.
+ * Default is one.
* </ul>
*/
public class HostManagerServlet extends HttpServlet implements ContainerServlet {
@@ -489,7 +489,7 @@ public class HostManagerServlet extends HttpServlet implements ContainerServlet
/**
- * Render a list of the currently active Contexts in our virtual host.
+ * Render a list of the currently active virtual hosts in our engine.
*
* @param writer Writer to render to
* @param smClient StringManager for the client's locale
@@ -652,7 +652,8 @@ public class HostManagerServlet extends HttpServlet implements ContainerServlet
*
* @return the config base for the host
*
- * @deprecated Unused. Will be removed in Tomcat 12. Use {@link #getConfigBase(String, PrintWriter, StringManager)}
+ * @deprecated Unused. Will be removed in a future version. Use
+ * {@link #getConfigBase(String, PrintWriter, StringManager)}
*/
@Deprecated
protected File getConfigBase(String hostName) {
diff --git a/java/org/apache/catalina/manager/util/SessionUtils.java b/java/org/apache/catalina/manager/util/SessionUtils.java
index 9b76ae540a..e504ec74c3 100644
--- a/java/org/apache/catalina/manager/util/SessionUtils.java
+++ b/java/org/apache/catalina/manager/util/SessionUtils.java
@@ -29,7 +29,7 @@ import jakarta.servlet.http.HttpSession;
import org.apache.catalina.Session;
/**
- * Utility methods on HttpSessions.
+ * Utility methods on {@link Session} and {@link HttpSession} objects.
*/
public class SessionUtils {
@@ -38,7 +38,7 @@ public class SessionUtils {
}
/**
- * The session attributes key under which the user's selected <code>java.util.Locale</code> is stored, if any.
+ * The session attribute keys under which the user's selected <code>java.util.Locale</code> is stored, if any.
*/
// org.apache.struts.Globals.LOCALE_KEY
private static final String STRUTS_LOCALE_KEY = "org.apache.struts.action.LOCALE";//$NON-NLS-1$
@@ -134,7 +134,8 @@ public class SessionUtils {
*
* @param in_session The session
*
- * @return the user
+ * @return the user, that is the name of the session principal if the session has one, otherwise a value guessed
+ * from the session attributes, or {@code null} if it cannot be determined
*/
public static Object guessUserFromSession(final Session in_session) {
if (null == in_session) {
@@ -196,10 +197,11 @@ public class SessionUtils {
/**
- * Returns the time in milliseconds that the session has been active.
+ * Returns the time in milliseconds between session creation and the session's last access.
*
* @param in_session The session
- * @return the active time in milliseconds, or -1 if the session is invalidated
+ * @return the time in milliseconds between session creation and the last access, or -1 if the session is
+ * invalidated
*/
public static long getUsedTimeForSession(Session in_session) {
try {
diff --git a/java/org/apache/catalina/mapper/Mapper.java b/java/org/apache/catalina/mapper/Mapper.java
index bfbc6e88b7..d240ab14ef 100644
--- a/java/org/apache/catalina/mapper/Mapper.java
+++ b/java/org/apache/catalina/mapper/Mapper.java
@@ -93,7 +93,7 @@ public final class Mapper {
// --------------------------------------------------------- Public Methods
/**
- * Set default host.
+ * Set default host. The host name is resolved case-sensitively against the registered host names and aliases.
*
* @param defaultHostName Default host name
*/
diff --git a/java/org/apache/catalina/mapper/MapperListener.java b/java/org/apache/catalina/mapper/MapperListener.java
index d6ee528498..35d18712d3 100644
--- a/java/org/apache/catalina/mapper/MapperListener.java
+++ b/java/org/apache/catalina/mapper/MapperListener.java
@@ -129,7 +129,7 @@ public class MapperListener extends LifecycleMBeanBase implements ContainerListe
@Override
protected String getObjectNameKeyProperties() {
- // Same as connector but Mapper rather than Connector
+ // The domain of the resulting ObjectName is the name of the owning Engine.
return "type=Mapper";
}
diff --git a/java/org/apache/catalina/mbeans/GlobalResourcesLifecycleListener.java b/java/org/apache/catalina/mbeans/GlobalResourcesLifecycleListener.java
index 28cd7caf01..2befb5a48e 100644
--- a/java/org/apache/catalina/mbeans/GlobalResourcesLifecycleListener.java
+++ b/java/org/apache/catalina/mbeans/GlobalResourcesLifecycleListener.java
@@ -43,9 +43,8 @@ import org.apache.tomcat.util.res.StringManager;
* Implementation of <code>LifecycleListener</code> that instantiates the set of MBeans associated with global JNDI
* resources that are subject to management.
* <p>
- * This listener must only be nested within {@link Server} elements.
- *
- * @since 4.1
+ * This listener should be nested within {@link Server} elements. If it is attached to any other component type, a
+ * warning is logged and the listener still processes the event.
*/
public class GlobalResourcesLifecycleListener implements LifecycleListener {
/**
diff --git a/java/org/apache/catalina/mbeans/MBeanDumper.java b/java/org/apache/catalina/mbeans/MBeanDumper.java
index 609c62a113..83d53e8b10 100644
--- a/java/org/apache/catalina/mbeans/MBeanDumper.java
+++ b/java/org/apache/catalina/mbeans/MBeanDumper.java
@@ -57,7 +57,7 @@ public class MBeanDumper {
/**
- * The following code to dump MBeans has been copied from JMXProxyServlet.
+ * Dump MBeans to a string. JMXProxyServlet uses this method to dump MBeans.
*
* @param mbeanServer the MBean server
* @param names a set of object names for which to dump the info
@@ -174,7 +174,7 @@ public class MBeanDumper {
* @return the escaped value
*/
public static String escape(String value) {
- // The only invalid char is \n
+ // \n is escaped to keep the output line-oriented. \r is not escaped.
// We also need to keep the string short and split it with \nSPACE
// XXX TODO
int idx = value.indexOf('\n');
diff --git a/java/org/apache/catalina/mbeans/MBeanFactory.java b/java/org/apache/catalina/mbeans/MBeanFactory.java
index 77d1cc74a7..9e5a5bcf12 100644
--- a/java/org/apache/catalina/mbeans/MBeanFactory.java
+++ b/java/org/apache/catalina/mbeans/MBeanFactory.java
@@ -301,7 +301,6 @@ public class MBeanFactory {
retobj.setSecure(isSSL);
retobj.setScheme(isSSL ? "https" : "http");
// Add the new instance to its parent component
- // FIX ME - addConnector will fail
ObjectName pname = new ObjectName(parent);
Service service = getService(pname);
service.addConnector(retobj);
diff --git a/java/org/apache/catalina/realm/DataSourceRealm.java b/java/org/apache/catalina/realm/DataSourceRealm.java
index 249e1d70ff..8d574a9b6a 100644
--- a/java/org/apache/catalina/realm/DataSourceRealm.java
+++ b/java/org/apache/catalina/realm/DataSourceRealm.java
@@ -243,9 +243,9 @@ public class DataSourceRealm extends RealmBase {
/**
* {@inheritDoc}
* <p>
- * If there are any errors with the JDBC connection, executing the query or anything this method returns null
- * (doesn't authenticate). This event is also logged, and the connection will be closed so that a subsequent request
- * will automatically re-open it.
+ * If there are any errors with the JDBC connection or executing the query, this method returns null (doesn't
+ * authenticate). Such errors are also logged. A fresh database connection is opened for each call and closed again
+ * before the method returns.
*/
@Override
public Principal authenticate(String username, String credentials) {
diff --git a/java/org/apache/catalina/realm/JAASMemoryLoginModule.java b/java/org/apache/catalina/realm/JAASMemoryLoginModule.java
index e60a900b25..7dca65e684 100644
--- a/java/org/apache/catalina/realm/JAASMemoryLoginModule.java
+++ b/java/org/apache/catalina/realm/JAASMemoryLoginModule.java
@@ -63,9 +63,9 @@ import org.apache.tomcat.util.digester.Digester;
* with a parameter of <code>"SHA256"</code></li>
* </ul>
* <p>
- * <strong>IMPLEMENTATION NOTE</strong> - This class implements <code>Realm</code> only to satisfy the calling
- * requirements of the <code>GenericPrincipal</code> constructor. It does not actually perform the functionality
- * required of a <code>Realm</code> implementation.
+ * <strong>IMPLEMENTATION NOTE</strong> - This class extends {@link MemoryRealm} rather than implementing
+ * <code>Realm</code> directly, so that user lookup and credential validation are performed against the XML file
+ * configured for the memory realm.
* </p>
*/
public class JAASMemoryLoginModule extends MemoryRealm implements LoginModule {
diff --git a/java/org/apache/catalina/realm/JNDIRealm.java b/java/org/apache/catalina/realm/JNDIRealm.java
index 03e912f120..64648778d0 100644
--- a/java/org/apache/catalina/realm/JNDIRealm.java
+++ b/java/org/apache/catalina/realm/JNDIRealm.java
@@ -80,7 +80,7 @@ import org.ietf.jgss.GSSName;
* <ul>
* <li>Each user that can be authenticated is represented by an individual element in the top level
* <code>DirContext</code> that is accessed via the <code>connectionURL</code> property.</li>
- * <li>If a socket connection cannot be made to the <code>connectURL</code> an attempt will be made to use the
+ * <li>If a socket connection cannot be made to the <code>connectionURL</code> an attempt will be made to use the
* <code>alternateURL</code> if it exists.</li>
* <li>Each user element has a distinguished name that can be formed by substituting the presented username into a
* pattern configured by the <code>userPattern</code> property.</li>
@@ -101,11 +101,10 @@ import org.ietf.jgss.GSSName;
* specified, in which case:
* <ul>
* <li>The element for this user must contain an attribute named by the <code>userPassword</code> property.
- * <li>The value of the user password attribute is either a cleartext String, or the result of passing a cleartext
- * String through the <code>RealmBase.digest()</code> method (using the standard digest support included in
- * <code>RealmBase</code>).
- * <li>The user is considered to be authenticated if the presented credentials (after being passed through
- * <code>RealmBase.digest()</code>) are equal to the retrieved value for the user password attribute.</li>
+ * <li>The value of the user password attribute is either a cleartext String, or the result of mutating a cleartext
+ * String using the configured <code>CredentialHandler</code>.
+ * <li>The user is considered to be authenticated if the presented credentials match the retrieved value for the user
+ * password attribute when compared using the configured <code>CredentialHandler</code>.</li>
* </ul>
* </li>
* <li>Each group of users that has been assigned a particular role may be represented by an individual element in the
@@ -241,9 +240,9 @@ public class JNDIRealm extends RealmBase {
protected String userRoleAttribute = null;
/**
- * A string of LDAP user patterns or paths, ":"-separated These will be used to form the distinguished name of a
- * user, with "{0}" marking the spot where the specified username goes. This is similar to userPattern, but allows
- * for multiple searches for a user.
+ * A string of LDAP user patterns or paths, each enclosed in parentheses. These will be used to form the
+ * distinguished name of a user, with "{0}" marking the spot where the specified username goes. This is similar to
+ * userPattern, but allows for multiple searches for a user.
*/
protected String[] userPatternArray = null;
diff --git a/java/org/apache/catalina/realm/LockOutRealm.java b/java/org/apache/catalina/realm/LockOutRealm.java
index 8da45febe2..d7f3c8772d 100644
--- a/java/org/apache/catalina/realm/LockOutRealm.java
+++ b/java/org/apache/catalina/realm/LockOutRealm.java
@@ -215,8 +215,8 @@ public class LockOutRealm extends CombinedRealm {
/**
- * Check if the current user is locked. If this is associated with a login attempt, then the last access
- * time will be recorded and any attempt to authenticate a locked user will log a warning.
+ * Check if the specified user is locked, that is, the user has at least the configured number of recent
+ * authentication failures and the lock out period has not yet expired.
*
* @param username The username to check
* @return true if the user is locked, false otherwise
diff --git a/java/org/apache/catalina/realm/MessageDigestCredentialHandler.java b/java/org/apache/catalina/realm/MessageDigestCredentialHandler.java
index b5ab367b84..cba86c78f0 100644
--- a/java/org/apache/catalina/realm/MessageDigestCredentialHandler.java
+++ b/java/org/apache/catalina/realm/MessageDigestCredentialHandler.java
@@ -33,12 +33,15 @@ import org.apache.tomcat.util.security.ConstantTime;
* This credential handler supports the following forms of stored passwords:
* <ul>
* <li><b>encodedCredential</b> - a hex encoded digest of the password digested using the configured digest</li>
- * <li><b>{MD5}encodedCredential</b> - a Base64 encoded MD5 digest of the password</li>
- * <li><b>{SHA}encodedCredential</b> - a Base64 encoded SHA1 digest of the password</li>
- * <li><b>{SSHA}encodedCredential</b> - 20 byte Base64 encoded SHA1 digest followed by variable length salt.
+ * <li><b>{MD5}encodedCredential</b> - a Base64 encoded digest of the password. The prefix only indicates the storage
+ * encoding used by some directories and databases; the digest is generated with the configured digest algorithm.</li>
+ * <li><b>{SHA}encodedCredential</b> - a Base64 encoded digest of the password. The prefix only indicates the storage
+ * encoding used by some directories and databases; the digest is generated with the configured digest algorithm.</li>
+ * <li><b>{SSHA}encodedCredential</b> - the Base64 encoding of a 20 byte digest of the password (generated with the
+ * configured digest algorithm) concatenated with a variable length salt.
*
* <pre>
- * {SSHA}<sha-1 digest:20><salt:n>
+ * {SSHA}<base64(<digest:20><salt:n>)>
* </pre>
*
* </li>
diff --git a/java/org/apache/catalina/realm/RealmBase.java b/java/org/apache/catalina/realm/RealmBase.java
index a526001c51..389a193962 100644
--- a/java/org/apache/catalina/realm/RealmBase.java
+++ b/java/org/apache/catalina/realm/RealmBase.java
@@ -338,9 +338,8 @@ public abstract class RealmBase extends LifecycleMBeanBase implements Realm {
* field's name, that is, the name of the field serves as the key of the mapping.
* <p>
* If set to the wildcard character, or, if the wildcard character is part of the comma separated list, all
- * available attributes - except the <i>password</i> attribute (as specified by <code>userCredCol</code>) - are
- * queried. The wildcard character is defined by constant {@link RealmBase#USER_ATTRIBUTES_WILDCARD}. It defaults to
- * the asterisk (*) character.
+ * available attributes - except the <i>password</i> attribute - are queried. The wildcard character is defined by
+ * constant {@link RealmBase#USER_ATTRIBUTES_WILDCARD}. It defaults to the asterisk (*) character.
*
* @param userAttributes the comma separated names of user attributes
*/
@@ -856,7 +855,7 @@ public abstract class RealmBase extends LifecycleMBeanBase implements Realm {
}
// Check for an all roles(role-name="*")
for (SecurityConstraint constraint : constraints) {
- // If the all roles mode exists, sets
+ // Check whether the constraint grants access to all roles (role-name="*")
if (constraint.getAllRoles()) {
if (allRolesMode == AllRolesMode.AUTH_ONLY_MODE) {
if (log.isTraceEnabled()) {
@@ -1154,7 +1153,7 @@ public abstract class RealmBase extends LifecycleMBeanBase implements Realm {
* @param realmName The realm name
* @param algorithm The name of the message digest algorithm to use
*
- * @return the digest for the specified user
+ * @return the digest for the specified user, or {@code null} if the user has no stored credential
*/
protected String getDigest(String username, String realmName, String algorithm) {
String password = getPassword(username);
@@ -1268,7 +1267,7 @@ public abstract class RealmBase extends LifecycleMBeanBase implements Realm {
if (isStripRealmForGss()) {
int i = name.indexOf('@');
if (i > 0) {
- // Zero so we don't leave a zero length name
+ // The 'i > 0' guard avoids stripping the name to an empty string when it starts with '@'
name = name.substring(0, i);
}
}
@@ -1325,8 +1324,9 @@ public abstract class RealmBase extends LifecycleMBeanBase implements Realm {
* the default for the CredentialHandler will be used.</li>
* <li><b>-k</b> - The length (in bits) of the key(s), if any, created while generating the credential. If not
* specified, the default for the CredentialHandler will be used.</li>
- * <li><b>-h</b> - The fully qualified class name of the CredentialHandler to use. If not specified, the built-in
- * handlers will be tested in turn and the first one to accept the specified algorithm will be used.</li>
+ * <li><b>-h</b> - The fully qualified class name of the {@link DigestCredentialHandlerBase} to use. If not
+ * specified, the built-in handlers will be tested in turn and the first one to accept the specified algorithm will
+ * be used.</li>
* <li><b>-f</b> - The name of the file that contains passwords to encode. Each line in the file should contain only
* one password. Using this option ignores other password input.</li>
* </ul>
diff --git a/java/org/apache/catalina/security/LocalStrings.properties b/java/org/apache/catalina/security/LocalStrings.properties
index 0be358ffc4..f22897c3ca 100644
--- a/java/org/apache/catalina/security/LocalStrings.properties
+++ b/java/org/apache/catalina/security/LocalStrings.properties
@@ -13,7 +13,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-SecurityListener.buildDateAgeUnreadable=Unable to read configured buildDateWarningAgeDays [{0}], using default of [{1}] days.
+SecurityListener.buildDateAgeUnreadable=Unable to read configured buildDateWarningAgeDays [{0}], keeping the previously configured value (default: [{1}] days).
SecurityListener.buildDateIsOld=This version of Tomcat was built more than {0} days ago. You should consider upgrading to the current version.
SecurityListener.buildDateUnreadable=Server build date [{0}] is unreadable as an ISO-8601 date.
SecurityListener.checkUmaskFail=Start attempted with umask setting of [{0}]. Running Tomcat without a umask at least as restrictive as [{1}] has been blocked by the Lifecycle listener org.apache.catalina.security.SecurityListener (usually configured in CATALINA_BASE/conf/server.xml)
@@ -24,6 +24,6 @@ SecurityListener.checkUserWarning=Start attempted while running as user [{0}]. R
listener.notServer=This listener must only be nested within Server elements, but is in [{0}].
-tlsCertRenewalListener.notRenewed=[{0}], TLS virtual host [{1}] with name [{2}] that expires on [{3}] is overdue for renewal
+tlsCertRenewalListener.notRenewed=[{0}], TLS virtual host [{1}] certificate with subject [{2}] that expires on [{3}] is overdue for renewal
tlsCertRenewalListener.reloadFailed=[{0}], TLS virtual host [{1}] reload of TLS configuration failed
-tlsCertRenewalListener.reloadSuccess=[{0}], TLS virtual host [{1}] reloaded TLS configuration
+tlsCertRenewalListener.reloadSuccess=[{0}], TLS virtual host [{1}] attempted to reload TLS configuration
diff --git a/java/org/apache/catalina/security/SecurityListener.java b/java/org/apache/catalina/security/SecurityListener.java
index 838309f33a..5acf512e30 100644
--- a/java/org/apache/catalina/security/SecurityListener.java
+++ b/java/org/apache/catalina/security/SecurityListener.java
@@ -35,7 +35,8 @@ import org.apache.tomcat.util.buf.StringUtils;
import org.apache.tomcat.util.res.StringManager;
/**
- * This listener must only be nested within {@link Server} elements.
+ * This listener should be nested within {@link Server} elements. If it is attached to any other component type, a
+ * warning is logged and the checks are still performed.
*/
public class SecurityListener implements LifecycleListener {
@@ -150,7 +151,7 @@ public class SecurityListener implements LifecycleListener {
try {
buildDateWarningAgeDays = Integer.parseInt(ageDays);
} catch (NumberFormatException nfe) {
- // Just use the default and warn the user
+ // Keep the previously configured value (or the default) and warn the user
log.warn(sm.getString("SecurityListener.buildDateAgeUnreadable", ageDays,
String.valueOf(DEFAULT_BUILD_DATE_WARNING_AGE_DAYS)));
}
diff --git a/java/org/apache/catalina/servlets/WebdavServlet.java b/java/org/apache/catalina/servlets/WebdavServlet.java
index cefb1ea412..cc7d031e0d 100644
--- a/java/org/apache/catalina/servlets/WebdavServlet.java
+++ b/java/org/apache/catalina/servlets/WebdavServlet.java
@@ -1075,7 +1075,8 @@ public class WebdavServlet extends DefaultServlet implements PeriodicEventListen
/**
- * PROPPATCH Method. Dead properties support is a SHOULD in the specification and are not implemented.
+ * PROPPATCH Method. Sets, removes or tests the properties of a resource. The updated properties are persisted
+ * through the configured {@link PropertyStore} and are returned by subsequent PROPFIND requests.
*
* @param req The Servlet request
* @param resp The Servlet response
diff --git a/java/org/apache/catalina/session/FileStore.java b/java/org/apache/catalina/session/FileStore.java
index 66dab8b072..85dea66a40 100644
--- a/java/org/apache/catalina/session/FileStore.java
+++ b/java/org/apache/catalina/session/FileStore.java
@@ -329,7 +329,7 @@ public final class FileStore extends StoreBase {
/**
* Return a File object representing the pathname to our session persistence directory, if any. The directory will
- * be created if it does not already exist.
+ * be created if it does not already exist. If a non-directory file exists at the pathname, it is deleted first.
*/
private synchronized File directory() throws IOException {
// Synchronised to avoid concurrent attempts to create the directory.
diff --git a/java/org/apache/catalina/session/ManagerBase.java b/java/org/apache/catalina/session/ManagerBase.java
index 57c2b6b26f..16bb91b071 100644
--- a/java/org/apache/catalina/session/ManagerBase.java
+++ b/java/org/apache/catalina/session/ManagerBase.java
@@ -833,7 +833,8 @@ public abstract class ManagerBase extends LifecycleMBeanBase implements Manager
* <p>
* This implementation excludes session attributes from distribution if the:
* <ul>
- * <li>attribute name matches {@link #getSessionAttributeNameFilter()}</li>
+ * <li>attribute name does not match {@link #getSessionAttributeNameFilter()}</li>
+ * <li>attribute value class name does not match {@link #getSessionAttributeValueClassNameFilter()}</li>
* </ul>
*/
@Override
diff --git a/java/org/apache/catalina/session/PersistentManagerBase.java b/java/org/apache/catalina/session/PersistentManagerBase.java
index 9c26fd0445..dcf0c8626e 100644
--- a/java/org/apache/catalina/session/PersistentManagerBase.java
+++ b/java/org/apache/catalina/session/PersistentManagerBase.java
@@ -85,9 +85,10 @@ public abstract class PersistentManagerBase extends ManagerBase implements Store
/**
- * The minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep the active
- * session count below maxActiveSessions. Setting to {@code -1} means sessions will not be swapped out to keep the
- * active session count down.
+ * The minimum time in seconds a session must be idle before it is eligible to be swapped to disk. This is enforced
+ * both when swapping out to keep the active session count below maxActiveSessions and, as a lower bound in addition
+ * to maxIdleSwap, when swapping out due to inactivity. Setting to {@code -1} means sessions will not be swapped
+ * out to keep the active session count down.
*/
protected int minIdleSwap = -1;
@@ -179,12 +180,12 @@ public abstract class PersistentManagerBase extends ManagerBase implements Store
/**
- * Returns the minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep
- * the active session count below maxActiveSessions.
+ * Returns the minimum time in seconds a session must be idle before it is eligible to be swapped to disk. This is
+ * enforced both when swapping out to keep the active session count below maxActiveSessions and, as a lower bound in
+ * addition to maxIdleSwap, when swapping out due to inactivity.
*
- * @return The minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep
- * the active session count below maxActiveSessions. A value of {@code -1} means sessions will not be
- * swapped out to keep the active session count down.
+ * @return The minimum time in seconds a session must be idle before it is eligible to be swapped to disk. A value
+ * of {@code -1} means sessions will not be swapped out to keep the active session count down.
*/
public int getMinIdleSwap() {
return minIdleSwap;
@@ -192,9 +193,10 @@ public abstract class PersistentManagerBase extends ManagerBase implements Store
/**
- * Sets the minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep the
- * active session count below maxActiveSessions. Setting to {@code -1} means sessions will not be swapped out to
- * keep the active session count down.
+ * Sets the minimum time in seconds a session must be idle before it is eligible to be swapped to disk. This is
+ * enforced both when swapping out to keep the active session count below maxActiveSessions and, as a lower bound in
+ * addition to maxIdleSwap, when swapping out due to inactivity. Setting to {@code -1} means sessions will not be
+ * swapped out to keep the active session count down.
*
* @param min time in seconds before a possible swap out
*/
diff --git a/java/org/apache/catalina/session/StoreBase.java b/java/org/apache/catalina/session/StoreBase.java
index 190808d35a..2be2526770 100644
--- a/java/org/apache/catalina/session/StoreBase.java
+++ b/java/org/apache/catalina/session/StoreBase.java
@@ -50,7 +50,8 @@ public abstract class StoreBase extends LifecycleBase implements Store {
// ----------------------------------------------------- Instance Variables
/**
- * Name to register for this Store, used for logging.
+ * The default store name, used for logging by the default {@link #getStoreName()} implementation. Concrete store
+ * implementations typically shadow this with their own name and override {@link #getStoreName()}.
*/
protected static final String storeName = "StoreBase";
@@ -119,9 +120,10 @@ public abstract class StoreBase extends LifecycleBase implements Store {
}
/**
- * Get only those keys of sessions, that are saved in the Store and are to be expired.
+ * Get the keys of sessions that are to be expired. The default implementation returns all keys that are saved in
+ * the Store. Subclasses may override this to return only the keys of sessions that are actually to be expired.
*
- * @return array of session keys, that are to be expired
+ * @return array of session keys
*
* @throws IOException if an input-/output error occurred
*/
diff --git a/java/org/apache/catalina/ssi/ByteArrayServletOutputStream.java b/java/org/apache/catalina/ssi/ByteArrayServletOutputStream.java
index 37d6502b72..4dc94f7f77 100644
--- a/java/org/apache/catalina/ssi/ByteArrayServletOutputStream.java
+++ b/java/org/apache/catalina/ssi/ByteArrayServletOutputStream.java
@@ -23,7 +23,8 @@ import jakarta.servlet.WriteListener;
/**
- * Class that extends ServletOutputStream, used as a wrapper from within <code>SSIInclude</code>
+ * Class that extends ServletOutputStream to capture output into an in-memory byte array. Used by
+ * <code>SSIFilter</code> and <code>SSIServletExternalResolver</code>.
*
* @see ServletOutputStream and ByteArrayOutputStream
*/
diff --git a/java/org/apache/catalina/ssi/ResponseIncludeWrapper.java b/java/org/apache/catalina/ssi/ResponseIncludeWrapper.java
index e8dc255db0..c418de2b5c 100644
--- a/java/org/apache/catalina/ssi/ResponseIncludeWrapper.java
+++ b/java/org/apache/catalina/ssi/ResponseIncludeWrapper.java
@@ -88,7 +88,7 @@ public class ResponseIncludeWrapper extends HttpServletResponseWrapper {
*
* @return a PrintWriter object
*
- * @exception java.io.IOException if the outputstream already been called
+ * @exception IllegalStateException if the output stream has already been returned
*/
@Override
public PrintWriter getWriter() throws IOException {
@@ -109,7 +109,7 @@ public class ResponseIncludeWrapper extends HttpServletResponseWrapper {
*
* @return an OutputStream object
*
- * @exception java.io.IOException if the printwriter already been called
+ * @exception IllegalStateException if the print writer has already been returned
*/
@Override
public ServletOutputStream getOutputStream() throws IOException {
diff --git a/java/org/apache/catalina/ssi/SSIExternalResolver.java b/java/org/apache/catalina/ssi/SSIExternalResolver.java
index 25c4e189e3..4c05cd5b5e 100644
--- a/java/org/apache/catalina/ssi/SSIExternalResolver.java
+++ b/java/org/apache/catalina/ssi/SSIExternalResolver.java
@@ -53,8 +53,9 @@ public interface SSIExternalResolver {
/**
- * Returns the current date. This is useful for putting the SSI stuff in a regression test. Since you can make the
- * current date a constant, it makes testing easier since the output won't change.
+ * Returns the current date. This is a hook that implementations may use to return a fixed date, e.g. to make SSI
+ * output deterministic for regression testing. Note that the built-in SSI date variables are not set from this
+ * method.
*
* @return the date
*/
diff --git a/java/org/apache/catalina/ssi/SSIServlet.java b/java/org/apache/catalina/ssi/SSIServlet.java
index 73f95e8e54..2a2fe53dea 100644
--- a/java/org/apache/catalina/ssi/SSIServlet.java
+++ b/java/org/apache/catalina/ssi/SSIServlet.java
@@ -57,7 +57,7 @@ public class SSIServlet extends HttpServlet {
protected boolean isVirtualWebappRelative = false;
/** Input encoding. If not specified, uses platform default */
protected String inputEncoding = null;
- /** Output encoding. If not specified, uses platform default */
+ /** Output encoding. Defaults to UTF-8. */
protected String outputEncoding = "UTF-8";
/** Allow exec (normally blocked for security) */
protected boolean allowExec = false;
@@ -151,7 +151,7 @@ public class SSIServlet extends HttpServlet {
log("SSIServlet.requestHandler()\n" + "Serving " + (buffered ? "buffered " : "unbuffered ") + "resource '" +
path + "'");
}
- // Exclude any resource in the /WEB-INF and /META-INF subdirectories
+ // Exclude any resource whose path starts with /WEB-INF or /META-INF
// (the "toUpperCase()" avoids problems on Windows systems)
if (path == null || path.toUpperCase(Locale.ENGLISH).startsWith("/WEB-INF") ||
path.toUpperCase(Locale.ENGLISH).startsWith("/META-INF")) {
diff --git a/java/org/apache/catalina/ssi/SSIServletRequestUtil.java b/java/org/apache/catalina/ssi/SSIServletRequestUtil.java
index d424ae2fb6..92914c4c44 100644
--- a/java/org/apache/catalina/ssi/SSIServletRequestUtil.java
+++ b/java/org/apache/catalina/ssi/SSIServletRequestUtil.java
@@ -30,8 +30,11 @@ public class SSIServletRequestUtil {
}
/**
- * Return the relative path associated with this servlet. Taken from DefaultServlet.java. Perhaps this should be put
- * in org.apache.catalina.util somewhere? Seems like it would be widely used.
+ * Return the relative path associated with this request. If the request
+ * was dispatched via {@link RequestDispatcher#include}, the path is taken
+ * from the include attributes. Otherwise it is taken from the path info,
+ * falling back to the servlet path. A {@code null} or empty path results
+ * in {@code /}.
*
* @param request The servlet request we are processing
*
diff --git a/java/org/apache/catalina/ssi/SSISet.java b/java/org/apache/catalina/ssi/SSISet.java
index 542c217e99..f74b4cddf8 100644
--- a/java/org/apache/catalina/ssi/SSISet.java
+++ b/java/org/apache/catalina/ssi/SSISet.java
@@ -42,7 +42,8 @@ public class SSISet implements SSICommand {
* @param paramValues the parameter values
* @param writer the print writer for output
*
- * @return the last modified timestamp
+ * @return the current time (in milliseconds) if a variable was set, or
+ * zero if no variable was set
*
* @throws SSIStopProcessingException if processing should stop
*/
diff --git a/java/org/apache/catalina/ssi/SSIStopProcessingException.java b/java/org/apache/catalina/ssi/SSIStopProcessingException.java
index de745df30e..d784a73ef3 100644
--- a/java/org/apache/catalina/ssi/SSIStopProcessingException.java
+++ b/java/org/apache/catalina/ssi/SSIStopProcessingException.java
@@ -19,8 +19,9 @@ package org.apache.catalina.ssi;
import java.io.Serial;
/**
- * Exception used to tell SSIProcessor that it should stop processing SSI commands. This is used to mimic the Apache
- * behavior in #set with invalid attributes.
+ * Exception used to tell SSIProcessor that it should stop processing SSI commands, causing the remainder of the
+ * document to be discarded. This is used, among other cases, to mimic the Apache behavior in #set with invalid
+ * attributes and for unparseable #if/#elif expressions.
*/
public class SSIStopProcessingException extends Exception {
diff --git a/java/org/apache/catalina/startup/Catalina.java b/java/org/apache/catalina/startup/Catalina.java
index 6cf5c80437..a3334c973d 100644
--- a/java/org/apache/catalina/startup/Catalina.java
+++ b/java/org/apache/catalina/startup/Catalina.java
@@ -91,7 +91,6 @@ public class Catalina {
*/
protected String configFile = SERVER_XML;
- // XXX Should be moved to embedded
/**
* The shared extensions class loader for this server.
*/
@@ -944,8 +943,7 @@ public class Catalina {
}
} catch (Throwable t) {
ExceptionUtils.handleThrowable(t);
- // This will fail on JDK 1.2. Ignoring, as Tomcat can run
- // fine without the shutdown hook.
+ // Failure to remove the shutdown hook is non-fatal
}
// Shut down the server
diff --git a/java/org/apache/catalina/startup/CatalinaProperties.java b/java/org/apache/catalina/startup/CatalinaProperties.java
index 3119f1dd58..49bafb2d13 100644
--- a/java/org/apache/catalina/startup/CatalinaProperties.java
+++ b/java/org/apache/catalina/startup/CatalinaProperties.java
@@ -120,7 +120,6 @@ public class CatalinaProperties {
}
if ((is == null)) {
- // Do something
log.warn("Failed to load catalina properties file");
// That's fine - we have reasonable defaults.
properties = new Properties();
diff --git a/java/org/apache/catalina/startup/ContextConfig.java b/java/org/apache/catalina/startup/ContextConfig.java
index 660c9473f9..15f121df57 100644
--- a/java/org/apache/catalina/startup/ContextConfig.java
+++ b/java/org/apache/catalina/startup/ContextConfig.java
@@ -1513,7 +1513,7 @@ public class ContextConfig implements LifecycleListener {
context.getNamingResources().addMessageDestinationRef(mdr);
}
- // messageDestinations were ignored in Tomcat 6, so ignore here
+ // message-destination declarations are not supported and are ignored
context.setMetadataComplete(webxml.isMetadataComplete());
for (Entry<String,String> entry : webxml.getMimeMappings().entrySet()) {
diff --git a/java/org/apache/catalina/startup/CredentialHandlerRuleSet.java b/java/org/apache/catalina/startup/CredentialHandlerRuleSet.java
index f6acdddf31..d33ea73721 100644
--- a/java/org/apache/catalina/startup/CredentialHandlerRuleSet.java
+++ b/java/org/apache/catalina/startup/CredentialHandlerRuleSet.java
@@ -27,6 +27,11 @@ import org.apache.tomcat.util.digester.RuleSet;
public class CredentialHandlerRuleSet implements RuleSet {
+ /**
+ * The maximum number of nested <code>CredentialHandler</code> levels to support. The default value of 3 can be
+ * overridden using the <code>org.apache.catalina.startup.CredentialHandlerRuleSet.MAX_NESTED_LEVELS</code> system
+ * property.
+ */
private static final int MAX_NESTED_LEVELS =
Integer.getInteger("org.apache.catalina.startup.CredentialHandlerRuleSet.MAX_NESTED_LEVELS", 3).intValue();
diff --git a/java/org/apache/catalina/startup/ExpandWar.java b/java/org/apache/catalina/startup/ExpandWar.java
index 1ea7cf0da7..d7a703ef4e 100644
--- a/java/org/apache/catalina/startup/ExpandWar.java
+++ b/java/org/apache/catalina/startup/ExpandWar.java
@@ -65,7 +65,8 @@ public class ExpandWar {
* @param war URL of the web application archive to be expanded (must start with "jar:")
* @param pathname Context path name for web application
*
- * @exception IllegalArgumentException if this is not a "jar:" URL or if the WAR file is invalid
+ * @exception ClassCastException if the WAR URL is not a "jar:" URL
+ * @exception IllegalArgumentException if a WAR entry path resolves outside the target directory
* @exception IOException if an input/output error was encountered during expansion
*
* @return The absolute path to the expanded directory for the given WAR
@@ -92,7 +93,7 @@ public class ExpandWar {
warLastModified = jfuc.getLastModified();
}
- // Check to see of the WAR has been expanded previously
+ // Check to see if the WAR has been expanded previously
if (docBase.exists()) {
// A WAR was expanded. Tomcat will have set the last modified
// time of warTracker file to the last modified time of the WAR so
@@ -194,7 +195,8 @@ public class ExpandWar {
* @param war URL of the web application archive to be validated (must start with "jar:")
* @param pathname Context path name for web application
*
- * @exception IllegalArgumentException if this is not a "jar:" URL or if the WAR file is invalid
+ * @exception ClassCastException if the WAR URL is not a "jar:" URL
+ * @exception IllegalArgumentException if a WAR entry path resolves outside the target directory
* @exception IOException if an input/output error was encountered during validation
*/
public static void validate(Host host, URL war, String pathname) throws IOException {
diff --git a/java/org/apache/catalina/startup/HostConfig.java b/java/org/apache/catalina/startup/HostConfig.java
index 9bf96b41b0..5e1dd88657 100644
--- a/java/org/apache/catalina/startup/HostConfig.java
+++ b/java/org/apache/catalina/startup/HostConfig.java
@@ -1805,9 +1805,6 @@ public class HostConfig implements LifecycleListener {
host.removeChild(host.findChild(contextName));
}
- // ----------------------------------------------------- Instance Variables
-
-
/**
* This class represents the state of a deployed application, as well as the monitored resources.
*/
diff --git a/java/org/apache/catalina/startup/Tomcat.java b/java/org/apache/catalina/startup/Tomcat.java
index 9c6a4620d9..135b41d4a2 100644
--- a/java/org/apache/catalina/startup/Tomcat.java
+++ b/java/org/apache/catalina/startup/Tomcat.java
@@ -311,7 +311,7 @@ public class Tomcat {
* TODO: add the rest
*
* @param contextPath The context mapping to use, "" for root context.
- * @param docBase Base directory for the context, for static files. Must exist, relative to the server home
+ * @param docBase Base directory for the context, for static files
*
* @return the deployed context
*/
@@ -635,7 +635,7 @@ public class Tomcat {
*
* @param host The host in which the context will be deployed
* @param contextPath The context mapping to use, "" for root context
- * @param dir Base directory for the context, for static files. Must exist, relative to the server home
+ * @param dir Base directory for the context, for static files
* @return the deployed context
* @see #addContext(String, String)
*/
@@ -649,7 +649,7 @@ public class Tomcat {
* @param host The host in which the context will be deployed
* @param contextPath The context mapping to use, "" for root context
* @param contextName The context name
- * @param dir Base directory for the context, for static files. Must exist, relative to the server home
+ * @param dir Base directory for the context, for static files
*
* @return the deployed context
*
@@ -955,7 +955,8 @@ public class Tomcat {
*
* @param host host for which the {@link Context} should be created, or <code>null</code> if default host should be
* used
- * @param url path of the webapp which should get the {@link Context}
+ * @param url context path of the {@link Context} to be created (used only in the error message if the context
+ * class cannot be instantiated)
*
* @return newly created {@link Context}
*/
diff --git a/java/org/apache/catalina/startup/Tool.java b/java/org/apache/catalina/startup/Tool.java
index 4eb1053657..8050a0ed20 100644
--- a/java/org/apache/catalina/startup/Tool.java
+++ b/java/org/apache/catalina/startup/Tool.java
@@ -33,7 +33,7 @@ import org.apache.juli.logging.LogFactory;
* <ul>
* <li>Passes the <code>catalina.home</code> system property configured with the pathname of the Tomcat installation
* directory.</li>
- * <li>Sets the system classpath to include <code>bootstrap.jar</code> and <code>$JAVA_HOME/lib/tools.jar</code>.</li>
+ * <li>Sets the system classpath to include <code>bootstrap.jar</code>.</li>
* </ul>
* <p>
* The command line to execute the tool looks like:
diff --git a/java/org/apache/catalina/startup/UserConfig.java b/java/org/apache/catalina/startup/UserConfig.java
index 465d95bbe9..cd5719ac11 100644
--- a/java/org/apache/catalina/startup/UserConfig.java
+++ b/java/org/apache/catalina/startup/UserConfig.java
@@ -38,7 +38,7 @@ import org.apache.tomcat.util.res.StringManager;
/**
* Startup event listener for a <b>Host</b> that configures Contexts (web applications) for all defined "users" who have
* a web application in a directory with the specified name in their home directories. The context path of each deployed
- * application will be set to <code>~xxxxx</code>, where xxxxx is the username of the owning user for that web
+ * application will be set to <code>/~xxxxx</code>, where xxxxx is the username of the owning user for that web
* application
*/
public final class UserConfig implements LifecycleListener {
diff --git a/java/org/apache/catalina/startup/WebAnnotationSet.java b/java/org/apache/catalina/startup/WebAnnotationSet.java
index b8ee369aed..d3cfd2c316 100644
--- a/java/org/apache/catalina/startup/WebAnnotationSet.java
+++ b/java/org/apache/catalina/startup/WebAnnotationSet.java
@@ -335,7 +335,7 @@ public class WebAnnotationSet {
} else {
/*
- * General case. Also used for: - javax.resource.cci.InteractionSpec - jakarta.transaction.UserTransaction
+ * General case. Also used for: - jakarta.resource.cci.InteractionSpec - jakarta.transaction.UserTransaction
*/
// resource-env-ref
diff --git a/java/org/apache/catalina/storeconfig/CatalinaClusterSF.java b/java/org/apache/catalina/storeconfig/CatalinaClusterSF.java
index 97db740c41..409c025866 100644
--- a/java/org/apache/catalina/storeconfig/CatalinaClusterSF.java
+++ b/java/org/apache/catalina/storeconfig/CatalinaClusterSF.java
@@ -59,8 +59,8 @@ public class CatalinaClusterSF extends StoreFactoryBase {
if (deployer != null) {
storeElement(aWriter, indent, deployer);
}
- // Store nested <Valve> element
- // ClusterValve are not store at Hosts element, see
+ // Store nested <Valve> elements. Cluster valves are stored here,
+ // not as <Valve> elements within the <Host> element.
Valve[] valves = cluster.getValves();
storeElementArray(aWriter, indent, valves);
diff --git a/java/org/apache/catalina/storeconfig/ConnectorStoreAppender.java b/java/org/apache/catalina/storeconfig/ConnectorStoreAppender.java
index e25e07d990..7377aef3ad 100644
--- a/java/org/apache/catalina/storeconfig/ConnectorStoreAppender.java
+++ b/java/org/apache/catalina/storeconfig/ConnectorStoreAppender.java
@@ -149,9 +149,8 @@ public class ConnectorStoreAppender extends StoreAppender {
*/
protected List<String> getPropertyKeys(Connector bean) throws IntrospectionException {
List<String> propertyKeys = new ArrayList<>();
- // Acquire the list of properties for this bean
ProtocolHandler protocolHandler = bean.getProtocolHandler();
- // Acquire the list of properties for this bean
+ // Acquire the list of property descriptors for this bean
PropertyDescriptor[] descriptors = Introspector.getBeanInfo(bean.getClass()).getPropertyDescriptors();
if (descriptors == null) {
descriptors = new PropertyDescriptor[0];
diff --git a/java/org/apache/catalina/storeconfig/IStoreConfig.java b/java/org/apache/catalina/storeconfig/IStoreConfig.java
index 63d725bce6..06bae3a3cf 100644
--- a/java/org/apache/catalina/storeconfig/IStoreConfig.java
+++ b/java/org/apache/catalina/storeconfig/IStoreConfig.java
@@ -31,14 +31,14 @@ public interface IStoreConfig {
/**
* Get Configuration Registry
*
- * @return aRegistry that handle the store operations
+ * @return the registry that handles the store operations
*/
StoreRegistry getRegistry();
/**
* Set Configuration Registry
*
- * @param aRegistry aregistry that handle the store operations
+ * @param aRegistry the registry that handles the store operations
*/
void setRegistry(StoreRegistry aRegistry);
diff --git a/java/org/apache/catalina/storeconfig/IStoreFactory.java b/java/org/apache/catalina/storeconfig/IStoreFactory.java
index adb08a033e..9238e3e55f 100644
--- a/java/org/apache/catalina/storeconfig/IStoreFactory.java
+++ b/java/org/apache/catalina/storeconfig/IStoreFactory.java
@@ -26,14 +26,14 @@ public interface IStoreFactory {
/**
* Get the store appender.
*
- * @return the writer
+ * @return the store appender
*/
StoreAppender getStoreAppender();
/**
* Set the store appender.
*
- * @param storeWriter the writer
+ * @param storeWriter the store appender
*/
void setStoreAppender(StoreAppender storeWriter);
diff --git a/java/org/apache/catalina/storeconfig/JarScannerSF.java b/java/org/apache/catalina/storeconfig/JarScannerSF.java
index 1a1f2c961f..48a6aa1e3a 100644
--- a/java/org/apache/catalina/storeconfig/JarScannerSF.java
+++ b/java/org/apache/catalina/storeconfig/JarScannerSF.java
@@ -33,7 +33,7 @@ public class JarScannerSF extends StoreFactoryBase {
}
/**
- * Store the specified JarScanner properties and children (JarScannerFilter)
+ * Store the specified JarScanner properties and children (JarScanFilter)
* <p>
* {@inheritDoc}
*/
diff --git a/java/org/apache/catalina/storeconfig/NamingResourcesSF.java b/java/org/apache/catalina/storeconfig/NamingResourcesSF.java
index 650c92038f..35e60db416 100644
--- a/java/org/apache/catalina/storeconfig/NamingResourcesSF.java
+++ b/java/org/apache/catalina/storeconfig/NamingResourcesSF.java
@@ -29,7 +29,7 @@ import org.apache.tomcat.util.descriptor.web.ContextResourceEnvRef;
import org.apache.tomcat.util.descriptor.web.ContextResourceLink;
/**
- * Store server.xml elements Resources at context and GlobalNamingResources
+ * Store server.xml element NamingResources
*/
public class NamingResourcesSF extends StoreFactoryBase {
diff --git a/java/org/apache/catalina/storeconfig/StandardContextSF.java b/java/org/apache/catalina/storeconfig/StandardContextSF.java
index 95450b65c1..8bf22a5675 100644
--- a/java/org/apache/catalina/storeconfig/StandardContextSF.java
+++ b/java/org/apache/catalina/storeconfig/StandardContextSF.java
@@ -50,8 +50,10 @@ import org.apache.tomcat.util.http.CookieProcessor;
/**
* Store server.xml Context element with all children
* <ul>
- * <li>Store all context at server.xml</li>
- * <li>Store existing app.xml context a conf/enginename/hostname/app.xml</li>
+ * <li>Store a context that has an external configuration file to that file</li>
+ * <li>Store a context without an external configuration file to
+ * conf/enginename/hostname/context.xml, unless the registry allows inline
+ * storage in server.xml</li>
* <li>Store with backup</li>
* </ul>
*/
diff --git a/java/org/apache/catalina/storeconfig/StoreDescription.java b/java/org/apache/catalina/storeconfig/StoreDescription.java
index 9d40bd1194..1e5a98beba 100644
--- a/java/org/apache/catalina/storeconfig/StoreDescription.java
+++ b/java/org/apache/catalina/storeconfig/StoreDescription.java
@@ -29,6 +29,7 @@ import java.util.List;
* standard="true"
* default="true"
* externalAllowed="true"
+ * externalOnly="true"
* storeSeparate="true"
* backup="true"
* children="true"
@@ -41,14 +42,17 @@ import java.util.List;
* <TransientAttribute>displayName</TransientAttribute>
* <TransientAttribute>distributable</TransientAttribute>
* <TransientAttribute>domain</TransientAttribute>
- * <TransientAttribute>engineName</TransientAttribute>
* <TransientAttribute>name</TransientAttribute>
* <TransientAttribute>publicId</TransientAttribute>
+ * <TransientAttribute>originalDocBase</TransientAttribute>
* <TransientAttribute>replaceWelcomeFiles</TransientAttribute>
- * <TransientAttribute>saveConfig</TransientAttribute>
* <TransientAttribute>sessionTimeout</TransientAttribute>
* <TransientAttribute>startupTime</TransientAttribute>
* <TransientAttribute>tldScanTime</TransientAttribute>
+ * <TransientAttribute>effectiveMajorVersion</TransientAttribute>
+ * <TransientAttribute>effectiveMinorVersion</TransientAttribute>
+ * <TransientAttribute>webappVersion</TransientAttribute>
+ * <TransientAttribute>metadataComplete</TransientAttribute>
* </Description>
* </pre>
*/
diff --git a/java/org/apache/catalina/storeconfig/StoreFactoryBase.java b/java/org/apache/catalina/storeconfig/StoreFactoryBase.java
index e1aa4d5900..5cbb2ede30 100644
--- a/java/org/apache/catalina/storeconfig/StoreFactoryBase.java
+++ b/java/org/apache/catalina/storeconfig/StoreFactoryBase.java
@@ -170,8 +170,8 @@ public class StoreFactoryBase implements IStoreFactory {
try {
storeElement(aWriter, indent, element);
} catch (IOException ignore) {
- // Ignore. Children report error themselves.
- // See StandardContext.storeWithBackup()
+ // Ignore. Children do not report the error themselves (e.g.
+ // StandardContextSF.storeWithBackup() throws without logging).
}
}
}
diff --git a/java/org/apache/catalina/storeconfig/StoreLoader.java b/java/org/apache/catalina/storeconfig/StoreLoader.java
index 7150495e61..73a7b9fd88 100644
--- a/java/org/apache/catalina/storeconfig/StoreLoader.java
+++ b/java/org/apache/catalina/storeconfig/StoreLoader.java
@@ -36,12 +36,8 @@ import org.apache.tomcat.util.file.ConfigurationSource.Resource;
* default="true"
* tagClass="org.apache.catalina.core.StandardServer"
* storeFactoryClass="org.apache.catalina.storeconfig.StandardServerSF">
- * <TransientAttributes>
- * <Attribute></Attribute>
- * </TransientAttributes>
- * <TransientChildren>
- * <Child></Child>
- * </TransientChildren>
+ * <TransientAttribute>domain</TransientAttribute>
+ * <TransientChild>org.apache.catalina.core.StandardContext</TransientChild>
* </Description>
* ...
* </Registry>
@@ -53,7 +49,7 @@ import org.apache.tomcat.util.file.ConfigurationSource.Resource;
* <li>Factories at subpackage <i>org.apache.catalina.storeconfig.xxxSF</i>.</li>
* <li>Element name are the unique Class name</li>
* <li>SF for StoreFactory</li>
- * <li>standard implementation is false</li>
+ * <li>standard implementation is true</li>
* </ul>
*/
public class StoreLoader {
diff --git a/java/org/apache/catalina/tribes/Channel.java b/java/org/apache/catalina/tribes/Channel.java
index 198e952a78..201feaa23b 100644
--- a/java/org/apache/catalina/tribes/Channel.java
+++ b/java/org/apache/catalina/tribes/Channel.java
@@ -463,9 +463,10 @@ public interface Channel {
}
/**
- * Translates a comma separated list of option names to their bitwise-ORd value
+ * Translates a channel send options specification to its bitwise-ORd value. The input is first attempted to be
+ * parsed as an integer bitmask. If that fails, the input is treated as a comma separated list of option names.
*
- * @param input A comma separated list of options, e.g. "async, multicast"
+ * @param input A comma separated list of options, e.g. "async, multicast", or an integer bitmask
*
* @return a bitwise ORd value of the passed option names
*/
diff --git a/java/org/apache/catalina/tribes/ChannelListener.java b/java/org/apache/catalina/tribes/ChannelListener.java
index a314c9b711..ab3fe77ddf 100644
--- a/java/org/apache/catalina/tribes/ChannelListener.java
+++ b/java/org/apache/catalina/tribes/ChannelListener.java
@@ -19,7 +19,7 @@ package org.apache.catalina.tribes;
import java.io.Serializable;
/**
- * An interface to listens to incoming messages from a channel.
+ * An interface to listen to incoming messages from a channel.
* <p>
* When a message is received, the Channel will invoke the channel listener in a conditional sequence.
* <code>if (listener.accept(msg,sender)) listener.messageReceived(msg,sender);</code>
diff --git a/java/org/apache/catalina/tribes/ChannelMessage.java b/java/org/apache/catalina/tribes/ChannelMessage.java
index 0a39e3df97..fac4185b41 100644
--- a/java/org/apache/catalina/tribes/ChannelMessage.java
+++ b/java/org/apache/catalina/tribes/ChannelMessage.java
@@ -100,14 +100,14 @@ public interface ChannelMessage extends Serializable, Cloneable {
/**
* Shallow clone, what gets cloned depends on the implementation
*
- * @return ChannelMessage
+ * @return a shallow copy of this ChannelMessage (cast to the concrete implementation type if needed)
*/
Object clone();
/**
* Deep clone, all fields MUST get cloned
*
- * @return ChannelMessage
+ * @return a deep copy of this ChannelMessage (cast to the concrete implementation type if needed)
*/
Object deepclone();
}
diff --git a/java/org/apache/catalina/tribes/ManagedChannel.java b/java/org/apache/catalina/tribes/ManagedChannel.java
index fa4b9fca49..0cd166b201 100644
--- a/java/org/apache/catalina/tribes/ManagedChannel.java
+++ b/java/org/apache/catalina/tribes/ManagedChannel.java
@@ -20,7 +20,7 @@ import java.util.Iterator;
/**
* A managed channel interface gives you access to the components of the channels such as senders, receivers,
- * interceptors etc for configurations purposes
+ * interceptors etc for configuration purposes
*/
public interface ManagedChannel extends Channel {
diff --git a/java/org/apache/catalina/tribes/Member.java b/java/org/apache/catalina/tribes/Member.java
index 240aa75b41..bb196e6740 100644
--- a/java/org/apache/catalina/tribes/Member.java
+++ b/java/org/apache/catalina/tribes/Member.java
@@ -27,14 +27,14 @@ import java.io.Serializable;
* <li>The host is what interface the member is listening to, to receive data</li>
* <li>The port is what port the member is listening to, to receive data</li>
* <li>The uniqueId defines the session id for the member. This is an important feature since a member that has crashed
- * and the starts up again on the same port/host is not guaranteed to be the same member, so no state transfers will
+ * and then starts up again on the same port/host is not guaranteed to be the same member, so no state transfers will
* ever be confused.</li>
* </ul>
*/
public interface Member extends Serializable {
/**
- * When a member leaves the cluster, the payload of the memberDisappeared member will be the following bytes. This
+ * When a member leaves the cluster, the command of the memberDisappeared member will be the following bytes. This
* indicates a soft shutdown, and not a crash
*/
byte[] SHUTDOWN_PAYLOAD = new byte[] { 66, 65, 66, 89, 45, 65, 76, 69, 88 };
diff --git a/java/org/apache/catalina/tribes/MembershipService.java b/java/org/apache/catalina/tribes/MembershipService.java
index b029ded6ec..7d9f305f94 100644
--- a/java/org/apache/catalina/tribes/MembershipService.java
+++ b/java/org/apache/catalina/tribes/MembershipService.java
@@ -49,7 +49,7 @@ public interface MembershipService {
/**
* Starts the membership service. If a membership listeners is added the listener will start to receive membership
- * events. Performs a start level 1 and 2
+ * events. Performs a start at {@link #MBR_RX} and {@link #MBR_TX} level
*
* @throws Exception if the service fails to start.
*/
@@ -62,7 +62,7 @@ public interface MembershipService {
* @param level - level MBR_RX starts listening for members, level MBR_TX starts broadcasting the server
*
* @throws Exception if the service fails to start.
- * @throws java.lang.IllegalArgumentException if the level is incorrect.
+ * @throws java.lang.IllegalArgumentException some implementations throw this if the level is incorrect
*/
void start(int level) throws Exception;
diff --git a/java/org/apache/catalina/tribes/UniqueId.java b/java/org/apache/catalina/tribes/UniqueId.java
index 35ef5ec31b..57b78df5d7 100644
--- a/java/org/apache/catalina/tribes/UniqueId.java
+++ b/java/org/apache/catalina/tribes/UniqueId.java
@@ -43,7 +43,7 @@ public final class UniqueId implements Serializable {
/**
* Constructs a new UniqueId from the given byte array.
*
- * @param id the byte array containing the identifier
+ * @param id the byte array containing the identifier. The array is retained by reference and must not be modified.
*/
public UniqueId(byte[] id) {
this.id = id;
diff --git a/java/org/apache/catalina/tribes/group/ChannelCoordinator.java b/java/org/apache/catalina/tribes/group/ChannelCoordinator.java
index 3bf64ebfff..e67a4fbbd5 100644
--- a/java/org/apache/catalina/tribes/group/ChannelCoordinator.java
+++ b/java/org/apache/catalina/tribes/group/ChannelCoordinator.java
@@ -80,6 +80,8 @@ public class ChannelCoordinator extends ChannelInterceptorBase implements Messag
*/
public ChannelCoordinator(ChannelReceiver receiver, ChannelSender sender, MembershipService service) {
+ // These option flags do not affect the send path of this coordinator (it never calls okToProcess). They are
+ // only visible to GroupChannel.checkOptionFlags() when optionCheck is enabled.
this.optionFlag = Channel.SEND_OPTIONS_BYTE_MESSAGE | Channel.SEND_OPTIONS_USE_ACK |
Channel.SEND_OPTIONS_SYNCHRONIZED_ACK;
diff --git a/java/org/apache/catalina/tribes/group/RpcChannel.java b/java/org/apache/catalina/tribes/group/RpcChannel.java
index ce31277b6f..ca64c5c61f 100644
--- a/java/org/apache/catalina/tribes/group/RpcChannel.java
+++ b/java/org/apache/catalina/tribes/group/RpcChannel.java
@@ -49,7 +49,7 @@ public class RpcChannel implements ChannelListener {
public static final int FIRST_REPLY = 1;
/**
- * Return replies from a majority of members.
+ * Return replies from at least half of the destination members.
*/
public static final int MAJORITY_REPLY = 2;
@@ -92,7 +92,8 @@ public class RpcChannel implements ChannelListener {
* @param message Serializable - the message you are sending out
* @param rpcOptions int - FIRST_REPLY, MAJORITY_REPLY or ALL_REPLY
* @param channelOptions channel sender options
- * @param timeout long - timeout in milliseconds, if no reply is received within this time null is returned
+ * @param timeout long - timeout in milliseconds, if the requested replies are not received within this time
+ * the replies received so far (possibly none) are returned
*
* @return Response[] - an array of response objects.
*
diff --git a/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java b/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java
index 493406de24..0e48975fe4 100644
--- a/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java
+++ b/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java
@@ -50,9 +50,9 @@ import org.apache.juli.logging.LogFactory;
/**
* Adds encryption using a pre-shared key. The length of the key (in bytes) must be acceptable for the encryption
- * algorithm being used. For example, for AES, you must use a key of either 16 bytes (128 bits, 24 bytes 192 bits), or
- * 32 bytes (256 bits). You can supply the raw key bytes by calling {@link #setEncryptionKey(byte[])} or the hex-encoded
- * binary bytes by calling {@link #setEncryptionKey(String)}.
+ * algorithm being used. For example, for AES, you must use a key of either 16 bytes (128 bits), 24 bytes (192 bits),
+ * or 32 bytes (256 bits). You can supply the raw key bytes by calling {@link #setEncryptionKey(byte[])} or the
+ * hex-encoded binary bytes by calling {@link #setEncryptionKey(String)}.
*/
public class EncryptInterceptor extends ChannelInterceptorBase implements EncryptInterceptorMBean {
@@ -170,8 +170,9 @@ public class EncryptInterceptor extends ChannelInterceptorBase implements Encryp
XByteBuffer xbb = msg.getMessage();
/*
- * Completely replace the message with the decrypted one. No need to replace time stamp. At this point it
- * will be the same as the trusted time stamp.
+ * Completely replace the message with the decrypted one. The ChannelData header timestamp is not part of
+ * the encrypted payload and is not replaced with the trusted timestamp. On an untampered wire it is the
+ * same as the trusted timestamp.
*/
xbb.clear();
xbb.append(data, 8, data.length - 8);
diff --git a/java/org/apache/catalina/tribes/group/interceptors/FragmentationInterceptor.java b/java/org/apache/catalina/tribes/group/interceptors/FragmentationInterceptor.java
index a0d9e2eaee..eea432a979 100644
--- a/java/org/apache/catalina/tribes/group/interceptors/FragmentationInterceptor.java
+++ b/java/org/apache/catalina/tribes/group/interceptors/FragmentationInterceptor.java
@@ -62,7 +62,7 @@ public class FragmentationInterceptor extends ChannelInterceptorBase implements
private int maxSize = 1024 * 100;
private long expire = 1000 * 60; // one minute expiration
/**
- * Flag indicating whether deep cloning is enabled for fragments.
+ * Fragments are always deep cloned before storage.
*/
protected final boolean deepclone = true;
diff --git a/java/org/apache/catalina/tribes/group/interceptors/NonBlockingCoordinator.java b/java/org/apache/catalina/tribes/group/interceptors/NonBlockingCoordinator.java
index c9a9c1f9c5..2a19fb97cc 100644
--- a/java/org/apache/catalina/tribes/group/interceptors/NonBlockingCoordinator.java
+++ b/java/org/apache/catalina/tribes/group/interceptors/NonBlockingCoordinator.java
@@ -51,7 +51,9 @@ import org.apache.juli.logging.LogFactory;
* groups automatically when members are discovered that weren't part of the
* </p>
* <p>
- * This algorithm is non blocking meaning it allows for transactions while the coordination phase is going on
+ * This algorithm is non blocking meaning it allows for transactions while the coordination phase is going on. Note
+ * that {@link #startElection(boolean)} itself blocks its caller for up to 15 seconds while waiting for an election
+ * request from a higher priority member.
* </p>
* <p>
* This implementation is based on a home brewed algorithm that uses the AbsoluteOrder of a membership to pass a token
@@ -727,7 +729,7 @@ public class NonBlockingCoordinator extends ChannelInterceptorBase {
fireInterceptorEvent(new CoordinationEvent(CoordinationEvent.EVT_MBR_DEL, this,
"Member remove(" + member.getName() + ")"));
if (started && (isCoordinator() || isHighest())) {
- startElection(true); // to do, if a member disappears, only the coordinator can start
+ startElection(true);
}
} catch (ChannelException x) {
log.error(sm.getString("nonBlockingCoordinator.memberDisappeared.failed"), x);
diff --git a/java/org/apache/catalina/tribes/group/interceptors/ThroughputInterceptorMBean.java b/java/org/apache/catalina/tribes/group/interceptors/ThroughputInterceptorMBean.java
index 94231e328c..e231028b8f 100644
--- a/java/org/apache/catalina/tribes/group/interceptors/ThroughputInterceptorMBean.java
+++ b/java/org/apache/catalina/tribes/group/interceptors/ThroughputInterceptorMBean.java
@@ -48,20 +48,20 @@ public interface ThroughputInterceptorMBean {
double getLastCnt();
/**
- * Returns the application-layer transmit rate in MB/s.
- * @return the MB/s rate
+ * Returns the cumulative amount of data transmitted at the application layer, in MB.
+ * @return the amount in MB
*/
double getMbAppTx();
/**
- * Returns the receive rate in MB/s.
- * @return the MB/s rate
+ * Returns the cumulative amount of data received, in MB.
+ * @return the amount in MB
*/
double getMbRx();
/**
- * Returns the transmit rate in MB/s.
- * @return the MB/s rate
+ * Returns the cumulative amount of data transmitted, in MB.
+ * @return the amount in MB
*/
double getMbTx();
@@ -90,8 +90,8 @@ public interface ThroughputInterceptorMBean {
long getRxStart();
/**
- * Returns the last transmit time.
- * @return the time
+ * Returns the accumulated total transmit time in seconds.
+ * @return the time in seconds
*/
double getTimeTx();
diff --git a/java/org/apache/catalina/tribes/group/interceptors/TwoPhaseCommitInterceptor.java b/java/org/apache/catalina/tribes/group/interceptors/TwoPhaseCommitInterceptor.java
index 5e4d98a170..822e531e18 100644
--- a/java/org/apache/catalina/tribes/group/interceptors/TwoPhaseCommitInterceptor.java
+++ b/java/org/apache/catalina/tribes/group/interceptors/TwoPhaseCommitInterceptor.java
@@ -33,7 +33,9 @@ import org.apache.juli.logging.Log;
import org.apache.juli.logging.LogFactory;
/**
- * Two-phase commit interceptor that ensures reliable message delivery.
+ * Two-phase commit interceptor. The sender transmits a confirmation message after each message. The receiver stores
+ * each message and only passes it on when the matching confirmation message is received. There is no retransmission,
+ * so a message whose confirmation is lost, or that arrives out of order, is dropped after the expiration time.
*/
public class TwoPhaseCommitInterceptor extends ChannelInterceptorBase {
@@ -64,7 +66,8 @@ public class TwoPhaseCommitInterceptor extends ChannelInterceptorBase {
protected long expire = 1000 * 60; // one minute expiration
/**
- * Whether to deep clone messages before storage.
+ * Whether the confirmation message is deep cloned (true) or shallow cloned (false) before it is sent. Messages
+ * that are stored for later delivery are always deep cloned.
*/
protected boolean deepclone = true;
diff --git a/java/org/apache/catalina/tribes/io/ChannelData.java b/java/org/apache/catalina/tribes/io/ChannelData.java
index d6c3707917..aad66da3db 100644
--- a/java/org/apache/catalina/tribes/io/ChannelData.java
+++ b/java/org/apache/catalina/tribes/io/ChannelData.java
@@ -172,7 +172,7 @@ public class ChannelData implements ChannelMessage {
return 4 + // options
8 + // timestamp off=4
4 + // unique id length off=12
- uniqueId.length + // id data off=12+uniqueId.length
+ uniqueId.length + // id data off=16
4 + // addr length off=12+uniqueId.length+4
((address != null) ? address.getDataLength() : 0) + // member data off=12+uniqueId.length+4+add.length
4 + // message length off=12+uniqueId.length+4+add.length+4
diff --git a/java/org/apache/catalina/tribes/io/ObjectReader.java b/java/org/apache/catalina/tribes/io/ObjectReader.java
index 6cf7d9811e..fd61dfe23d 100644
--- a/java/org/apache/catalina/tribes/io/ObjectReader.java
+++ b/java/org/apache/catalina/tribes/io/ObjectReader.java
@@ -122,7 +122,7 @@ public class ObjectReader {
* @param len length in buffer
* @param count whether to return the count
*
- * @return number of messages that was sent to callback (or -1 if count == false)
+ * @return the number of complete packages currently in the buffer (or -1 if count == false)
*/
public int append(ByteBuffer data, int len, boolean count) {
buffer.append(data, len);
@@ -140,7 +140,7 @@ public class ObjectReader {
* @param off The offset in the array
* @param len The length of data
* @param count Whether to count packages
- * @return Number of messages sent to callback, or -1 if count is false
+ * @return The number of complete packages currently in the buffer, or -1 if count is false
*/
public int append(byte[] data, int off, int len, boolean count) {
buffer.append(data, off, len);
diff --git a/java/org/apache/catalina/tribes/io/XByteBuffer.java b/java/org/apache/catalina/tribes/io/XByteBuffer.java
index 8da41cf7bc..10e8e8e27e 100644
--- a/java/org/apache/catalina/tribes/io/XByteBuffer.java
+++ b/java/org/apache/catalina/tribes/io/XByteBuffer.java
@@ -77,8 +77,9 @@ public class XByteBuffer implements Serializable {
protected int bufSize = 0;
/**
- * Flag for discarding invalid packages If this flag is set to true, and append(byte[],...) is called, the data
- * added will be inspected, and if it doesn't start with <code>START_DATA</code> it will be thrown away.
+ * Flag for discarding invalid packages. If this flag is set to true, and append(byte[],...) is called, the
+ * buffer will be inspected, and if it is longer than <code>START_DATA</code> and does not contain
+ * <code>START_DATA</code> it will be reset to length 0.
*/
protected boolean discard;
@@ -368,8 +369,7 @@ public class XByteBuffer implements Serializable {
if (index != start || ((bufSize - start) < 14)) {
break;
}
- // next 4 bytes are compress flag not needed for count packages
- // then get the size 4 bytes
+ // next 4 bytes are the size of the package
int size = toInt(buf, pos);
// now the total buffer has to be long enough to hold
// START_DATA.length+4+size+END_DATA.length
diff --git a/java/org/apache/catalina/tribes/jmx/JmxRegistry.java b/java/org/apache/catalina/tribes/jmx/JmxRegistry.java
index 4abf3026d2..1803072961 100644
--- a/java/org/apache/catalina/tribes/jmx/JmxRegistry.java
+++ b/java/org/apache/catalina/tribes/jmx/JmxRegistry.java
@@ -54,7 +54,8 @@ public class JmxRegistry {
* Get the JMX registry for the given channel.
*
* @param channel the channel
- * @return the JMX registry, or {@code null} if JMX is not enabled
+ * @return the JMX registry, or {@code null} if the channel or its name is null, the channel is not a
+ * {@link JmxChannel}, JMX is not enabled for the channel, or the base ObjectName cannot be created
*/
public static JmxRegistry getRegistry(Channel channel) {
if (channel == null || channel.getName() == null) {
diff --git a/java/org/apache/catalina/tribes/membership/Constants.java b/java/org/apache/catalina/tribes/membership/Constants.java
index c146217ed8..3409c2d9d5 100644
--- a/java/org/apache/catalina/tribes/membership/Constants.java
+++ b/java/org/apache/catalina/tribes/membership/Constants.java
@@ -19,7 +19,7 @@ package org.apache.catalina.tribes.membership;
import org.apache.catalina.tribes.util.Arrays;
/**
- * Manifest constants for the <code>org.apache.catalina.tribes.membership</code> package.
+ * Constants for the <code>org.apache.catalina.tribes.membership</code> package.
*/
public class Constants {
diff --git a/java/org/apache/catalina/tribes/membership/McastService.java b/java/org/apache/catalina/tribes/membership/McastService.java
index d873139415..a368eae81f 100644
--- a/java/org/apache/catalina/tribes/membership/McastService.java
+++ b/java/org/apache/catalina/tribes/membership/McastService.java
@@ -94,14 +94,17 @@ public class McastService extends MembershipServiceBase implements MessageListen
* Sets the properties for the membership service.
*
* @param properties <br>
- * All are required<br>
+ * All of the following are required before {@code start()} is called<br>
* 1. mcastPort - the port to listen to<BR>
* 2. mcastAddress - the mcast group address<BR>
- * 4. bindAddress - the bind address if any - only one that can be null<BR>
- * 5. memberDropTime - the time a member is gone before it is considered gone.<BR>
- * 6. mcastFrequency - the frequency of sending messages<BR>
- * 7. tcpListenPort - the port this member listens to<BR>
- * 8. tcpListenHost - the bind address of this member<BR>
+ * 3. memberDropTime - the time a member is gone before it is considered gone.<BR>
+ * 4. mcastFrequency - the frequency of sending messages<BR>
+ * 5. tcpListenPort - the port this member listens to<BR>
+ * 6. tcpListenHost - the bind address of this member<BR>
+ * 7. tcpSecurePort - the secure port of this member<BR>
+ * 8. udpListenPort - the UDP port of this member<BR>
+ * Optionally:<BR>
+ * mcastBindAddress - the multicast bind address, if any<BR>
*
* @exception java.lang.IllegalArgumentException if a property is missing.
*/
diff --git a/java/org/apache/catalina/tribes/membership/McastServiceImpl.java b/java/org/apache/catalina/tribes/membership/McastServiceImpl.java
index 41c5488512..1eec1a731c 100644
--- a/java/org/apache/catalina/tribes/membership/McastServiceImpl.java
+++ b/java/org/apache/catalina/tribes/membership/McastServiceImpl.java
@@ -40,10 +40,9 @@ import org.apache.juli.logging.Log;
import org.apache.juli.logging.LogFactory;
/**
- * A <b>membership</b> implementation using simple multicast. This is the representation of a multicast membership
- * service. This class is responsible for maintaining a list of active cluster nodes in the cluster. If a node fails to
- * send out a heartbeat, the node will be dismissed. This is the low level implementation that handles the multicasting
- * sockets.
+ * A <b>membership</b> implementation using simple multicast. This class is responsible for maintaining a list of
+ * active cluster nodes in the cluster. If a node fails to send out a heartbeat, the node will be dismissed. This is the
+ * low level implementation that handles the multicasting sockets.
*/
public class McastServiceImpl extends MembershipProviderBase {
diff --git a/java/org/apache/catalina/tribes/membership/MemberImpl.java b/java/org/apache/catalina/tribes/membership/MemberImpl.java
index 387a08e73e..ded0596239 100644
--- a/java/org/apache/catalina/tribes/membership/MemberImpl.java
+++ b/java/org/apache/catalina/tribes/membership/MemberImpl.java
@@ -28,8 +28,7 @@ import org.apache.catalina.tribes.transport.SenderState;
import org.apache.catalina.tribes.util.StringManager;
/**
- * A <b>membership</b> implementation using simple multicast. This is the representation of a multicast member. Carries
- * the host, and port of the this or other cluster nodes.
+ * This is the representation of a multicast member. Carries the host, and port of the this or other cluster nodes.
*/
public class MemberImpl implements Member, java.io.Externalizable {
diff --git a/java/org/apache/catalina/tribes/membership/Membership.java b/java/org/apache/catalina/tribes/membership/Membership.java
index 63163040d0..3c9fda58d4 100644
--- a/java/org/apache/catalina/tribes/membership/Membership.java
+++ b/java/org/apache/catalina/tribes/membership/Membership.java
@@ -24,9 +24,8 @@ import java.util.HashMap;
import org.apache.catalina.tribes.Member;
/**
- * A <b>membership</b> implementation using simple multicast. This is the representation of a multicast membership. This
- * class is responsible for maintaining a list of active cluster nodes in the cluster. If a node fails to send out a
- * heartbeat, the node will be dismissed.
+ * This is the representation of a multicast membership. This class is responsible for maintaining a list of active
+ * cluster nodes in the cluster. If a node fails to send out a heartbeat, the node will be dismissed.
*/
public class Membership implements Cloneable {
diff --git a/java/org/apache/catalina/tribes/membership/StaticMembershipServiceMBean.java b/java/org/apache/catalina/tribes/membership/StaticMembershipServiceMBean.java
index 68cb01d73e..281857914e 100644
--- a/java/org/apache/catalina/tribes/membership/StaticMembershipServiceMBean.java
+++ b/java/org/apache/catalina/tribes/membership/StaticMembershipServiceMBean.java
@@ -59,7 +59,8 @@ public interface StaticMembershipServiceMBean {
// Operation
/**
* Returns the configuration properties.
- * @return the properties
+ * @return the live, internal Properties object; it is mutable and can be used to modify the service
+ * configuration through the returned reference
*/
Properties getProperties();
diff --git a/java/org/apache/catalina/tribes/membership/cloud/AbstractStreamProvider.java b/java/org/apache/catalina/tribes/membership/cloud/AbstractStreamProvider.java
index d0efb464e8..5c49db073c 100644
--- a/java/org/apache/catalina/tribes/membership/cloud/AbstractStreamProvider.java
+++ b/java/org/apache/catalina/tribes/membership/cloud/AbstractStreamProvider.java
@@ -74,7 +74,9 @@ public abstract class AbstractStreamProvider implements StreamProvider {
/**
* Returns the SSL socket factory.
*
- * @return the socket factory, or null if not needed
+ * @return the socket factory, or {@code null} if not needed. Implementations that may open HTTPS connections must
+ * not return {@code null} since the returned factory is applied unconditionally to HTTPS connections
+ * by {@link #openStream(String, Map, int, int)}.
*/
protected abstract SSLSocketFactory getSocketFactory();
diff --git a/java/org/apache/catalina/tribes/tipis/AbstractReplicatedMap.java b/java/org/apache/catalina/tribes/tipis/AbstractReplicatedMap.java
index 8748964113..46380ba8b2 100644
--- a/java/org/apache/catalina/tribes/tipis/AbstractReplicatedMap.java
+++ b/java/org/apache/catalina/tribes/tipis/AbstractReplicatedMap.java
@@ -68,7 +68,7 @@ public abstract class AbstractReplicatedMap<K, V>
private final Log log = LogFactory.getLog(AbstractReplicatedMap.class); // must not be static
/**
- * The default initial capacity - MUST be a power of two.
+ * The default initial capacity.
*/
public static final int DEFAULT_INITIAL_CAPACITY = 16;
@@ -1131,7 +1131,7 @@ public abstract class AbstractReplicatedMap<K, V>
* @param key Object
* @param value Object
*
- * @return Member - the backup node
+ * @return Member[] - the backup nodes
*
* @throws ChannelException Cluster error
*/
@@ -1468,8 +1468,6 @@ public abstract class AbstractReplicatedMap<K, V>
*/
@Override
public Set<K> keySet() {
- // todo implement
- // should only return keys where this is active.
LinkedHashSet<K> set = new LinkedHashSet<>(innerMap.size());
for (Entry<K,MapEntry<K,V>> e : innerMap.entrySet()) {
K key = e.getKey();
diff --git a/java/org/apache/catalina/tribes/tipis/LazyReplicatedMap.java b/java/org/apache/catalina/tribes/tipis/LazyReplicatedMap.java
index 248eab3f7a..8780a50564 100644
--- a/java/org/apache/catalina/tribes/tipis/LazyReplicatedMap.java
+++ b/java/org/apache/catalina/tribes/tipis/LazyReplicatedMap.java
@@ -32,7 +32,7 @@ import org.apache.juli.logging.LogFactory;
* primary and one node is always the backup. This map is synchronized across a cluster, and only has one backup
* member.<br>
* A perfect usage for this map would be a session map for a session manager in a clustered environment.<br>
- * The only way to modify this list is to use the <code>put, putAll, remove</code> methods. entrySet, entrySetFull,
+ * The only way to modify this map is to use the <code>put, putAll, remove</code> methods. entrySet, entrySetFull,
* keySet, keySetFull, returns all non modifiable sets.<br>
* <br>
* If objects (values) in the map change without invoking <code>put()</code> or <code>remove()</code> the data can be
@@ -59,8 +59,6 @@ import org.apache.juli.logging.LogFactory;
* node as primary. <br>
* <br>
* <b>REMEMBER TO CALL</b> <code>breakdown()</code> when you are done with the map to avoid memory leaks.<br>
- * <br>
- * TODO implement periodic sync/transfer thread
*
* @param <K> The type of Key
* @param <V> The type of Value
diff --git a/java/org/apache/catalina/tribes/tipis/ReplicatedMap.java b/java/org/apache/catalina/tribes/tipis/ReplicatedMap.java
index 527a8d9ee1..bbb7e69f3b 100644
--- a/java/org/apache/catalina/tribes/tipis/ReplicatedMap.java
+++ b/java/org/apache/catalina/tribes/tipis/ReplicatedMap.java
@@ -47,9 +47,6 @@ import org.apache.juli.logging.LogFactory;
* node as primary. <br>
* <br>
* <b>REMEMBER TO CALL <code>breakdown()</code> when you are done with the map to avoid memory leaks.</b><br>
- * <br>
- * TODO implement periodic sync/transfer thread<br>
- * TODO memberDisappeared, should do nothing except change map membership by default it relocates the primary objects
*
* @param <K> The type of Key
* @param <V> The type of Value
diff --git a/java/org/apache/catalina/tribes/tipis/ReplicatedMapEntry.java b/java/org/apache/catalina/tribes/tipis/ReplicatedMapEntry.java
index c05864879f..03d1b9478a 100644
--- a/java/org/apache/catalina/tribes/tipis/ReplicatedMapEntry.java
+++ b/java/org/apache/catalina/tribes/tipis/ReplicatedMapEntry.java
@@ -27,7 +27,7 @@ import java.io.Serializable;
* try {
* 2. entry.lock();<br>
* 3. byte[] diff = entry.getDiff();<br>
- * 4. entry.reset();<br>
+ * 4. entry.resetDiff();<br>
* } finally {<br>
* 5. entry.unlock();<br>
* }<br>
@@ -132,7 +132,8 @@ public interface ReplicatedMapEntry extends Serializable {
void setLastTimeReplicated(long lastTimeReplicated);
/**
- * If this returns true, to replicate that an object has been accessed
+ * Whether the object should be replicated to the backup nodes when it is accessed
+ * (see {@link #accessEntry()}) without being modified.
*
* @return boolean
*/
diff --git a/java/org/apache/catalina/tribes/transport/DataSender.java b/java/org/apache/catalina/tribes/transport/DataSender.java
index 4d02686b01..2d8e1d2f81 100644
--- a/java/org/apache/catalina/tribes/transport/DataSender.java
+++ b/java/org/apache/catalina/tribes/transport/DataSender.java
@@ -59,7 +59,7 @@ public interface DataSender {
/**
* Keepalive.
*
- * @return {@code true} if kept alive
+ * @return {@code true} if the connection (or an idle pooled connection) was disconnected
*/
boolean keepalive();
diff --git a/java/org/apache/catalina/tribes/transport/ReceiverBase.java b/java/org/apache/catalina/tribes/transport/ReceiverBase.java
index 0ca6f9700e..85166eb824 100644
--- a/java/org/apache/catalina/tribes/transport/ReceiverBase.java
+++ b/java/org/apache/catalina/tribes/transport/ReceiverBase.java
@@ -259,7 +259,7 @@ public abstract class ReceiverBase implements ChannelReceiver, ListenCallback, R
* @param portstart Starting port for bind attempts
* @param retries Number of times to attempt to bind (port incremented between attempts)
*
- * @return int The retry count
+ * @return int 0 on success; the non-positive retry count if no bind attempt was made
*
* @throws IOException Socket bind error
*/
diff --git a/java/org/apache/catalina/tribes/transport/RxTaskPool.java b/java/org/apache/catalina/tribes/transport/RxTaskPool.java
index bf75c9aa05..c2169f7f96 100644
--- a/java/org/apache/catalina/tribes/transport/RxTaskPool.java
+++ b/java/org/apache/catalina/tribes/transport/RxTaskPool.java
@@ -46,7 +46,6 @@ public class RxTaskPool {
* @throws Exception if initialization fails
*/
public RxTaskPool(int maxTasks, int minTasks, TaskCreator creator) throws Exception {
- // fill up the pool with worker threads
this.maxTasks = maxTasks;
this.minTasks = minTasks;
this.creator = creator;
@@ -64,9 +63,9 @@ public class RxTaskPool {
}
/**
- * Find an idle worker thread, if any. Could return null.
+ * Find an idle worker thread, creating a new one if needed. Blocks until a worker is available.
*
- * @return a worker
+ * @return a worker, or null if the pool has been stopped
*/
public AbstractRxTask getRxTask() {
AbstractRxTask worker = null;
diff --git a/java/org/apache/catalina/tribes/transport/nio/NioReceiver.java b/java/org/apache/catalina/tribes/transport/nio/NioReceiver.java
index 8602710505..e390f7c2f7 100644
--- a/java/org/apache/catalina/tribes/transport/nio/NioReceiver.java
+++ b/java/org/apache/catalina/tribes/transport/nio/NioReceiver.java
@@ -503,9 +503,8 @@ public class NioReceiver extends ReceiverBase implements Runnable, NioReceiverMB
NioReplicationTask task = (NioReplicationTask) getTaskPool().getRxTask();
if (task == null) {
// No threads/tasks available, do nothing, the selection
- // loop will keep calling this method until a
- // thread becomes available, the thread pool itself has a waiting mechanism
- // so we will not wait here.
+ // loop will keep calling this method. getRxTask() blocks until a task
+ // is released, so it only returns null after the pool has been stopped.
if (log.isDebugEnabled()) {
log.debug(sm.getString("nioReceiver.noThread"));
}
diff --git a/java/org/apache/catalina/tribes/transport/nio/NioReplicationTask.java b/java/org/apache/catalina/tribes/transport/nio/NioReplicationTask.java
index fa283949c7..94dfa766c0 100644
--- a/java/org/apache/catalina/tribes/transport/nio/NioReplicationTask.java
+++ b/java/org/apache/catalina/tribes/transport/nio/NioReplicationTask.java
@@ -44,7 +44,8 @@ import org.apache.juli.logging.LogFactory;
/**
* A worker thread class which drains a channel and processes received messages.
* Each instance services a single SelectionKey per invocation. After completion,
- * the worker returns itself to its parent pool for reuse.
+ * the worker returns itself to its parent pool for reuse, unless the key is null
+ * in which case it returns early without doing so.
*/
public class NioReplicationTask extends AbstractRxTask {
diff --git a/java/org/apache/catalina/tribes/transport/nio/NioSender.java b/java/org/apache/catalina/tribes/transport/nio/NioSender.java
index de0e497cf5..9ec53b4740 100644
--- a/java/org/apache/catalina/tribes/transport/nio/NioSender.java
+++ b/java/org/apache/catalina/tribes/transport/nio/NioSender.java
@@ -214,7 +214,8 @@ public class NioSender extends AbstractSender {
/**
* Reads acknowledgment data from the channel.
*
- * @return {@code true} if there is more data to read
+ * @return {@code true} if the read phase is complete (acknowledgment received, or there was nothing to read),
+ * {@code false} if more data is still needed
*
* @throws IOException If an I/O error occurs
*/
diff --git a/java/org/apache/catalina/tribes/transport/nio/ParallelNioSender.java b/java/org/apache/catalina/tribes/transport/nio/ParallelNioSender.java
index 067254f17c..9663df083f 100644
--- a/java/org/apache/catalina/tribes/transport/nio/ParallelNioSender.java
+++ b/java/org/apache/catalina/tribes/transport/nio/ParallelNioSender.java
@@ -61,7 +61,7 @@ public class ParallelNioSender extends AbstractSender implements MultiPointSende
/**
* The timeout in milliseconds for the selector select operation.
*/
- protected final long selectTimeout = 5000; // default 5 seconds, same as send timeout
+ protected final long selectTimeout = 5000; // default 5 seconds
/**
* Construct a new {@code ParallelNioSender}.
diff --git a/java/org/apache/catalina/tribes/util/StringManager.java b/java/org/apache/catalina/tribes/util/StringManager.java
index 650f257b58..9363ae7fcc 100644
--- a/java/org/apache/catalina/tribes/util/StringManager.java
+++ b/java/org/apache/catalina/tribes/util/StringManager.java
@@ -209,9 +209,10 @@ public class StringManager {
Map<Locale,StringManager> map = managers.get(packageName);
if (map == null) {
/*
- * Don't want the HashMap size to exceed LOCALE_CACHE_SIZE. Expansion occurs when size() exceeds capacity.
- * Therefore keep size at or below capacity. removeEldestEntry() executes after insertion therefore the test
- * for removal needs to use one less than the maximum desired size. Note this is an LRU cache.
+ * Don't want the HashMap size to exceed LOCALE_CACHE_SIZE. Expansion occurs when size() exceeds capacity
+ * times the load factor. Therefore keep size at or below capacity. removeEldestEntry() executes after
+ * insertion therefore the test for removal needs to use one less than the maximum desired size. Note this
+ * is an LRU cache.
*/
map = new LinkedHashMap<>(LOCALE_CACHE_SIZE, 0.75f, true) {
@Serial
diff --git a/java/org/apache/catalina/users/DataSourceUserDatabaseFactory.java b/java/org/apache/catalina/users/DataSourceUserDatabaseFactory.java
index c88ac8d2bc..64ffa94f2f 100644
--- a/java/org/apache/catalina/users/DataSourceUserDatabaseFactory.java
+++ b/java/org/apache/catalina/users/DataSourceUserDatabaseFactory.java
@@ -39,6 +39,19 @@ import javax.sql.DataSource;
* <ul>
* <li><strong>dataSourceName</strong> - JNDI name of the DataSource, which must be located in the same Context
* environment as the UserDatabase</li>
+ * <li><strong>readonly</strong> - whether the user database is read only</li>
+ * <li><strong>userTable</strong> - table that holds user data</li>
+ * <li><strong>groupTable</strong> - table that holds group data</li>
+ * <li><strong>roleTable</strong> - table that holds role data</li>
+ * <li><strong>userRoleTable</strong> - table that holds the relation between users and roles</li>
+ * <li><strong>userGroupTable</strong> - table that holds the relation between users and groups</li>
+ * <li><strong>groupRoleTable</strong> - table that holds the relation between groups and roles</li>
+ * <li><strong>roleNameCol</strong> - column in the user role table that names a role</li>
+ * <li><strong>roleAndGroupDescriptionCol</strong> - column used for role and group descriptions</li>
+ * <li><strong>groupNameCol</strong> - column used for group names</li>
+ * <li><strong>userCredCol</strong> - column in the user table that holds the user's credentials</li>
+ * <li><strong>userFullNameCol</strong> - column used for user full names</li>
+ * <li><strong>userNameCol</strong> - column in the user table that holds the user's name</li>
* </ul>
*/
public class DataSourceUserDatabaseFactory implements ObjectFactory {
diff --git a/java/org/apache/catalina/users/MemoryUserDatabaseFactory.java b/java/org/apache/catalina/users/MemoryUserDatabaseFactory.java
index 3806dce72c..75f0cda69f 100644
--- a/java/org/apache/catalina/users/MemoryUserDatabaseFactory.java
+++ b/java/org/apache/catalina/users/MemoryUserDatabaseFactory.java
@@ -39,9 +39,9 @@ import javax.naming.spi.ObjectFactory;
* <li><strong>pathname</strong> - Absolute or relative (to the directory path specified by the
* <code>catalina.base</code> system property) pathname to the XML file from which our user information is loaded, and
* to which it is stored. [conf/tomcat-users.xml]</li>
+ * <li><strong>readonly</strong> - whether the user database is read only</li>
+ * <li><strong>watchSource</strong> - whether to watch the source file for changes</li>
* </ul>
- *
- * @since 4.1
*/
public class MemoryUserDatabaseFactory implements ObjectFactory {
@@ -58,8 +58,9 @@ public class MemoryUserDatabaseFactory implements ObjectFactory {
/**
* <p>
* Create and return a new <code>MemoryUserDatabase</code> instance that has been configured according to the
- * properties of the specified <code>Reference</code>. If the instance cannot be created, return <code>null</code>
- * instead.
+ * properties of the specified <code>Reference</code>. Returns <code>null</code> if the object is not a
+ * <code>Reference</code> with a class name of <code>org.apache.catalina.UserDatabase</code>; other failures are
+ * reported as exceptions.
* </p>
*
* @param obj The possibly null object containing location or reference information that can be used in
diff --git a/java/org/apache/catalina/util/ContextName.java b/java/org/apache/catalina/util/ContextName.java
index 34d2e38f5b..01cf3805c7 100644
--- a/java/org/apache/catalina/util/ContextName.java
+++ b/java/org/apache/catalina/util/ContextName.java
@@ -100,7 +100,9 @@ public final class ContextName {
/**
* Construct an instance from a path and version.
*
- * @param path Context path to use, which must not contain a version marker
+ * @param path Context path to use, which must not contain a version marker. May be <code>null</code>,
+ * <code>""</code>, <code>"/"</code> or <code>"/ROOT"</code> to represent the root context. Any
+ * other value must start with <code>"/"</code>
* @param version Context version to use
*/
public ContextName(String path, String version) {
diff --git a/java/org/apache/catalina/util/CustomObjectInputStream.java b/java/org/apache/catalina/util/CustomObjectInputStream.java
index 79b3de1ed6..8b0ec3a49f 100644
--- a/java/org/apache/catalina/util/CustomObjectInputStream.java
+++ b/java/org/apache/catalina/util/CustomObjectInputStream.java
@@ -70,8 +70,9 @@ public final class CustomObjectInputStream extends ObjectInputStream {
*
* @param stream The input stream we will read from
* @param classLoader The class loader used to instantiate objects
- * @param log The logger to use to report any issues. It may only be null if the filterMode does
- * not require logging
+ * @param log The logger to use to report any issues. It may only be null if
+ * <code>warnOnFailure</code> is <code>false</code> or
+ * <code>allowedClassNamePattern</code> is <code>null</code>
* @param allowedClassNamePattern The regular expression to use to filter deserialized classes. The fully qualified
* class name must match this pattern for deserialization to be allowed.
* If null, filtering will be disabled.
diff --git a/java/org/apache/catalina/util/LifecycleMBeanBase.java b/java/org/apache/catalina/util/LifecycleMBeanBase.java
index 23df4e4326..8c49675a4d 100644
--- a/java/org/apache/catalina/util/LifecycleMBeanBase.java
+++ b/java/org/apache/catalina/util/LifecycleMBeanBase.java
@@ -112,7 +112,7 @@ public abstract class LifecycleMBeanBase extends LifecycleBase implements JmxEna
* Note: This method should only be used once {@link #initInternal()} has been called and before
* {@link #destroyInternal()} has been called.
*
- * @param obj The object the register
+ * @param obj The object to register
* @param objectNameKeyProperties The key properties component of the object name to use to register the object
*
* @return The name used to register the object
diff --git a/java/org/apache/catalina/util/NetMask.java b/java/org/apache/catalina/util/NetMask.java
index 70ca7839ad..90b39dd95a 100644
--- a/java/org/apache/catalina/util/NetMask.java
+++ b/java/org/apache/catalina/util/NetMask.java
@@ -186,7 +186,7 @@ public final class NetMask {
* @param addr The {@link java.net.InetAddress} to test
* @param port The port to test
*
- * @return true on match, false otherwise
+ * @return true on match, false otherwise. Always returns false if this netmask does not contain a port pattern
*/
public boolean matches(final InetAddress addr, int port) {
if (!foundPort) {
diff --git a/java/org/apache/catalina/util/NetMaskSet.java b/java/org/apache/catalina/util/NetMaskSet.java
index 6a1e6cd042..81dc4d0234 100644
--- a/java/org/apache/catalina/util/NetMaskSet.java
+++ b/java/org/apache/catalina/util/NetMaskSet.java
@@ -66,11 +66,11 @@ public class NetMaskSet {
/**
* Tests if the provided IP address matches any of the {@link NetMask}s in the set.
*
- * @param ipAddress an IP address to check
+ * @param ipAddress an IP address or hostname to check
*
* @return {@code true} if the passed IP address is matched by any of the {@link NetMask}s in the set
*
- * @throws UnknownHostException if the passed input is not a valid IP address
+ * @throws UnknownHostException if the passed input cannot be resolved to an IP address
*/
public boolean contains(String ipAddress) throws UnknownHostException {
diff --git a/java/org/apache/catalina/util/SessionIdGeneratorBase.java b/java/org/apache/catalina/util/SessionIdGeneratorBase.java
index 5785f4ea8b..e2a3d93f3e 100644
--- a/java/org/apache/catalina/util/SessionIdGeneratorBase.java
+++ b/java/org/apache/catalina/util/SessionIdGeneratorBase.java
@@ -195,7 +195,8 @@ public abstract class SessionIdGeneratorBase extends LifecycleBase implements Se
/**
* Set the number of bytes used for a session ID.
*
- * @param sessionIdLength the number of bytes
+ * @param sessionIdLength the number of bytes. Values less than 2 are rejected with a warning and the previous
+ * value is retained
*/
@Override
public void setSessionIdLength(int sessionIdLength) {
diff --git a/java/org/apache/catalina/util/StringUtil.java b/java/org/apache/catalina/util/StringUtil.java
index db297ecc46..9cc055c1ef 100644
--- a/java/org/apache/catalina/util/StringUtil.java
+++ b/java/org/apache/catalina/util/StringUtil.java
@@ -23,7 +23,8 @@ import java.util.regex.Pattern;
*/
public class StringUtil {
/**
- * Constructs a new StringUtil. This utility class should not be instantiated.
+ * Constructs a new StringUtil. This utility class provides only static methods and does not need to be
+ * instantiated.
*/
public StringUtil() {
}
@@ -34,8 +35,8 @@ public class StringUtil {
private static final Pattern commaSeparatedValuesPattern = Pattern.compile("\\s*,\\s*");
/**
- * Splits a comma-separated string into an array of String values. Whitespace around the commas is removed. Null or
- * empty values will return a zero-element array.
+ * Splits a comma-separated string into an array of String values. Whitespace around the commas between values is
+ * removed. Null or empty values will return a zero-element array.
*
* @param s The string to split by commas.
*
diff --git a/java/org/apache/catalina/util/TLSUtil.java b/java/org/apache/catalina/util/TLSUtil.java
index 99c0605d7a..5cc1ac1ba9 100644
--- a/java/org/apache/catalina/util/TLSUtil.java
+++ b/java/org/apache/catalina/util/TLSUtil.java
@@ -25,7 +25,7 @@ import org.apache.tomcat.util.net.SSLSupport;
public class TLSUtil {
/**
- * Constructs a new TLSUtil. This utility class should not be instantiated.
+ * Constructs a new TLSUtil. This utility class provides only static methods and does not need to be instantiated.
*/
public TLSUtil() {
}
diff --git a/java/org/apache/catalina/util/TomcatCSS.java b/java/org/apache/catalina/util/TomcatCSS.java
index b9139a37db..d67adb0e09 100644
--- a/java/org/apache/catalina/util/TomcatCSS.java
+++ b/java/org/apache/catalina/util/TomcatCSS.java
@@ -23,7 +23,8 @@ package org.apache.catalina.util;
public class TomcatCSS {
/**
- * Constructs a new TomcatCSS. This utility class should not be instantiated.
+ * Constructs a new TomcatCSS. This utility class provides only a static constant and does not need to be
+ * instantiated.
*/
public TomcatCSS() {
}
diff --git a/java/org/apache/catalina/util/URLEncoder.java b/java/org/apache/catalina/util/URLEncoder.java
index 18d3ae74b0..c260550dd4 100644
--- a/java/org/apache/catalina/util/URLEncoder.java
+++ b/java/org/apache/catalina/util/URLEncoder.java
@@ -25,8 +25,7 @@ import java.util.BitSet;
/**
* This class is very similar to the java.net.URLEncoder class. Unfortunately, with java.net.URLEncoder there is no way
- * to specify to the java.net.URLEncoder which characters should NOT be encoded. This code was moved from
- * DefaultServlet.java
+ * to specify to the java.net.URLEncoder which characters should NOT be encoded.
*/
public final class URLEncoder implements Cloneable {
@@ -177,7 +176,8 @@ public final class URLEncoder implements Cloneable {
* happen. The only Tomcat code that currently (January 2026) might call this method with something other than
* UTF-8 is the rewrite valve. In that case, the rewrite rules should be consistent with the configured URI
* encoding on the Connector. Given all of this, the IAE is only expected to be thrown as a result of
- * configuration errors.
+ * configuration errors. Note that unpaired surrogate characters are not reported by the UTF-8 encoder and are
+ * silently dropped.
*/
OutputStreamWriter writer = new OutputStreamWriter(buf, charset.newEncoder()
.onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT));
diff --git a/java/org/apache/catalina/valves/AbstractAccessLogValve.java b/java/org/apache/catalina/valves/AbstractAccessLogValve.java
index 0293476c9e..c2d9e9a802 100644
--- a/java/org/apache/catalina/valves/AbstractAccessLogValve.java
+++ b/java/org/apache/catalina/valves/AbstractAccessLogValve.java
@@ -74,7 +74,7 @@ import org.apache.tomcat.util.net.IPv6Utils;
* <li><b><code>%l</code></b> - Remote logical username from identd (always returns '-')
* <li><b><code>%m</code></b> - Request method
* <li><b><code>%p</code></b> - Local port
- * <li><b><code>%q</code></b> - Query string (prepended with a '?' if it exists, otherwise an empty string
+ * <li><b><code>%q</code></b> - Query string (prepended with a '?' if it exists, otherwise '-')
* <li><b><code>%r</code></b> - First line of the request
* <li><b><code>%s</code></b> - HTTP status code of the response
* <li><b><code>%S</code></b> - User session ID
@@ -2290,8 +2290,9 @@ public abstract class AbstractAccessLogValve extends ValveBase implements Access
* - %to trailer response header - %V server name per UseCanonicalName setting
*
* The following escaped elements are not escaped in Tomcat because values that would require escaping are rejected
- * before they reach the AccessLogValve: - %h remote host - %H request protocol - %m request method - %v canonical
- * server name
+ * before they reach the AccessLogValve: - %H request protocol - %m request method - %v canonical server name
+ * Note that %h is also not escaped but, when <code>enableLookups</code> is true, its value comes from a DNS
+ * lookup which is not validated.
*
* The following escaped elements are supported by Tomcat: - %{}i request header - %{}o response header - %u remote
* user
diff --git a/java/org/apache/catalina/valves/ErrorReportValve.java b/java/org/apache/catalina/valves/ErrorReportValve.java
index b525cdbd31..550f80bae5 100644
--- a/java/org/apache/catalina/valves/ErrorReportValve.java
+++ b/java/org/apache/catalina/valves/ErrorReportValve.java
@@ -428,7 +428,8 @@ public class ErrorReportValve extends ValveBase {
/**
* Sets a property for error page configuration. Properties starting with "errorCode." or "exceptionType." are used
- * to configure error pages.
+ * to configure error pages. Note that subclasses that do not generate HTML error pages (e.g.
+ * {@link JsonErrorReportValve}) ignore the configured error pages.
*
* @param name The property name
* @param value The property value
diff --git a/java/org/apache/catalina/valves/ExtendedAccessLogValve.java b/java/org/apache/catalina/valves/ExtendedAccessLogValve.java
index fe18c81d94..ff60efa82a 100644
--- a/java/org/apache/catalina/valves/ExtendedAccessLogValve.java
+++ b/java/org/apache/catalina/valves/ExtendedAccessLogValve.java
@@ -59,7 +59,9 @@ import org.apache.tomcat.util.ExceptionUtils;
* <li><code>sc(xxx)</code>: The value of header xxx from server to client</li>
* <li><code>sc-status</code>: The status code</li>
* <li><code>time</code>: Time the request was served</li>
- * <li><code>time-taken</code>: Time (in seconds) taken to serve the request</li>
+ * <li><code>time-taken</code>: Time taken to serve the request. In seconds by default; one of the suffixes
+ * <code>-ms</code>, <code>-us</code>, <code>-ns</code> or <code>-fracsec</code> may be appended to select the unit
+ * (unknown suffixes default to seconds)</li>
* <li><code>x-threadname</code>: Current request thread name (can compare later with stacktraces)</li>
* <li><code>x-A(xxx)</code>: Pull xxx attribute from the servlet context</li>
* <li><code>x-C(xxx)</code>: Pull the cookie(s) of the name xxx</li>
diff --git a/java/org/apache/catalina/valves/LoadBalancerDrainingValve.java b/java/org/apache/catalina/valves/LoadBalancerDrainingValve.java
index df895a8f7f..49c1463157 100644
--- a/java/org/apache/catalina/valves/LoadBalancerDrainingValve.java
+++ b/java/org/apache/catalina/valves/LoadBalancerDrainingValve.java
@@ -70,14 +70,14 @@ public class LoadBalancerDrainingValve extends ValveBase {
private int _redirectStatusCode = HttpServletResponse.SC_TEMPORARY_REDIRECT;
/**
- * The name of the cookie which can be set to ignore the "draining" action of this Filter. This will allow a client
+ * The name of the cookie which can be set to ignore the "draining" action of this Valve. This will allow a client
* to contact the server without being re-balanced to another server. The expected cookie value can be set in the
* {@link #_ignoreCookieValue}. The cookie name and value must match to avoid being re-balanced.
*/
private String _ignoreCookieName;
/**
- * The value of the cookie which can be set to ignore the "draining" action of this Filter. This will allow a client
+ * The value of the cookie which can be set to ignore the "draining" action of this Valve. This will allow a client
* to contact the server without being re-balanced to another server. The expected cookie name can be set in the
* {@link #_ignoreCookieName}. The cookie name and value must match to avoid being re-balanced.
*/
diff --git a/java/org/apache/catalina/valves/LocalStrings.properties b/java/org/apache/catalina/valves/LocalStrings.properties
index 4a9383a247..d3c9e5cbc1 100644
--- a/java/org/apache/catalina/valves/LocalStrings.properties
+++ b/java/org/apache/catalina/valves/LocalStrings.properties
@@ -180,7 +180,7 @@ sslValve.invalidProvider=The SSL provider specified on the connector associated
stuckThreadDetectionValve.interrupted=Thread interrupted after the request is finished, ignoring
stuckThreadDetectionValve.notifyStuckThreadCompleted=Thread [{0}] (id=[{3}]) was previously reported to be stuck but has completed. It was active for approximately [{1}] milliseconds.{2,choice,0#|0< There is/are still [{2}] thread(s) that are monitored by this Valve and may be stuck.}
-stuckThreadDetectionValve.notifyStuckThreadDetected=Thread [{0}] (id=[{6}]) has been active for [{1}] milliseconds (since [{2}]) to serve the same request for [{4}] and may be stuck (configured threshold for this StuckThreadDetectionValve is [{5}] seconds). There is/are [{3}] thread(s) in total that are monitored by this Valve and may be stuck.
+stuckThreadDetectionValve.notifyStuckThreadDetected=Thread [{0}] (id=[{6}]) has been active for [{1}] milliseconds (since [{2}]) to serve the same request for [{4}] and may be stuck (configured threshold for this StuckThreadDetectionValve is [{5}] seconds). There is/are [{3}] thread(s) in total currently detected as stuck.
stuckThreadDetectionValve.notifyStuckThreadInterrupted=Thread [{0}] (id=[{5}]) has been interrupted because it was active for [{1}] milliseconds (since [{2}]) to serve the same request for [{3}] and was probably stuck (configured interruption threshold for this StuckThreadDetectionValve is [{4}] seconds).
valveBase.noContainer=A Container must be configured before a Valve can be initialized
diff --git a/java/org/apache/catalina/valves/ParameterLimitValve.java b/java/org/apache/catalina/valves/ParameterLimitValve.java
index ae269a800b..7392368b9f 100644
--- a/java/org/apache/catalina/valves/ParameterLimitValve.java
+++ b/java/org/apache/catalina/valves/ParameterLimitValve.java
@@ -45,8 +45,9 @@ import org.apache.tomcat.util.file.ConfigurationSource;
* <ul>
* <li>URL-specific parameter limits that can be defined using regular expressions</li>
* <li>Configurable through Tomcat's <code>server.xml</code> or <code>context.xml</code></li>
- * <li>Requires a <code>parameter_limit.config</code> file containing the URL-specific parameter limits. It must be
- * placed in the Host configuration folder or in the WEB-INF folder of the web application.</li>
+ * <li>URL-specific parameter limits may optionally be defined in a <code>parameter_limit.config</code> file. When
+ * present, it must be placed in the Host configuration folder or in the WEB-INF folder of the web application. Without
+ * this file the valve can be configured dynamically using the management operations.</li>
* </ul>
* <p>
* The default limit, specified by Connector's value, applies to all requests unless a more specific URL pattern is
diff --git a/java/org/apache/catalina/valves/RemoteIpValve.java b/java/org/apache/catalina/valves/RemoteIpValve.java
index 2a8f6729bb..568fa9927c 100644
--- a/java/org/apache/catalina/valves/RemoteIpValve.java
+++ b/java/org/apache/catalina/valves/RemoteIpValve.java
@@ -119,7 +119,7 @@ import org.apache.tomcat.util.http.parser.Host;
* </tr>
* <tr>
* <td>protocolHeader</td>
- * <td>Name of the http header read by this valve that holds the flag that this request</td>
+ * <td>Name of the http header read by this valve that holds the flag that this request was made over https</td>
* <td>N/A</td>
* <td>Compliant http header name like <code>X-Forwarded-Proto</code>, <code>X-Forwarded-Ssl</code> or
* <code>Front-End-Https</code></td>
@@ -227,7 +227,7 @@ import org.apache.tomcat.util.http.parser.Host;
* internalProxies="192.168.0.10/31"
* remoteIpHeader="x-forwarded-for"
* proxiesHeader="x-forwarded-by"
- * trustedProxies="proxy1|proxy2"
+ * trustedProxies="proxy1, proxy2"
* /></code>
* <table border="1">
* <caption>Request Values</caption>
@@ -270,7 +270,7 @@ import org.apache.tomcat.util.http.parser.Host;
* internalProxies="192.168.0.10/31"
* remoteIpHeader="x-forwarded-for"
* proxiesHeader="x-forwarded-by"
- * trustedProxies="proxy1|proxy2"
+ * trustedProxies="proxy1, proxy2"
* /></code>
* <table border="1">
* <caption>Request Values</caption>
@@ -314,7 +314,7 @@ import org.apache.tomcat.util.http.parser.Host;
* internalProxies="192.168.0.10/31"
* remoteIpHeader="x-forwarded-for"
* proxiesHeader="x-forwarded-by"
- * trustedProxies="proxy1|proxy2"
+ * trustedProxies="proxy1, proxy2"
* /></code>
* <table border="1">
* <caption>Request Values</caption>
@@ -340,7 +340,7 @@ import org.apache.tomcat.util.http.parser.Host;
* </tr>
* </table>
* <p>
- * Note : <code>x-forwarded-by</code> holds the trusted proxy <code>proxy1</code>. <code>x-forwarded-by</code> holds
+ * Note : <code>x-forwarded-by</code> holds the trusted proxy <code>proxy1</code>. <code>x-forwarded-for</code> holds
* <code>140.211.11.130</code> because <code>untrusted-proxy</code> is not trusted and thus, we cannot trust that
* <code>untrusted-proxy</code> is the actual remote ip. <code>request.remoteAddr</code> is <code>untrusted-proxy</code>
* that is an IP verified by <code>proxy1</code>.
diff --git a/java/org/apache/catalina/valves/StuckThreadDetectionValve.java b/java/org/apache/catalina/valves/StuckThreadDetectionValve.java
index 92d9d868a9..e42e83baea 100644
--- a/java/org/apache/catalina/valves/StuckThreadDetectionValve.java
+++ b/java/org/apache/catalina/valves/StuckThreadDetectionValve.java
@@ -54,7 +54,7 @@ public class StuckThreadDetectionValve extends ValveBase {
private static final StringManager sm = StringManager.getManager(Constants.Package);
/**
- * Keeps count of the number of stuck threads detected
+ * Keeps count of the number of threads currently detected as stuck
*/
private final AtomicInteger stuckCount = new AtomicInteger(0);
@@ -115,7 +115,7 @@ public class StuckThreadDetectionValve extends ValveBase {
/**
* Specifies the threshold (in seconds) before stuck threads are interrupted. If <=0, the interruption is
- * disabled. The default is -1. If >=0, the value must actually be >= threshold.
+ * disabled. The default is -1.
*
* @param interruptThreadThreshold The new thread interruption threshold in seconds
*/
diff --git a/java/org/apache/catalina/valves/ValveBase.java b/java/org/apache/catalina/valves/ValveBase.java
index b5318392f9..876430bfae 100644
--- a/java/org/apache/catalina/valves/ValveBase.java
+++ b/java/org/apache/catalina/valves/ValveBase.java
@@ -29,8 +29,8 @@ import org.apache.tomcat.util.res.StringManager;
/**
* Convenience base class for implementations of the <b>Valve</b> interface. A subclass <strong>MUST</strong> implement
- * an <code>invoke()</code> method to provide the required functionality, and <strong>MAY</strong> implement the
- * <code>Lifecycle</code> interface to provide configuration management and lifecycle support.
+ * an <code>invoke()</code> method to provide the required functionality. Configuration management and lifecycle
+ * support are provided by this class.
*/
public abstract class ValveBase extends LifecycleMBeanBase implements Contained, Valve {
diff --git a/java/org/apache/catalina/valves/rewrite/RewriteRule.java b/java/org/apache/catalina/valves/rewrite/RewriteRule.java
index 3a30daf4ec..c525546272 100644
--- a/java/org/apache/catalina/valves/rewrite/RewriteRule.java
+++ b/java/org/apache/catalina/valves/rewrite/RewriteRule.java
@@ -223,7 +223,7 @@ public class RewriteRule {
/**
* This sets a cookie on the client's browser. The cookie's name is specified by NAME and the value is VAL. The
* domain field is the domain of the cookie, such as '.apache.org',the optional lifetime is the lifetime of the
- * cookie in minutes, and the optional path is the path of the cookie
+ * cookie in seconds, and the optional path is the path of the cookie
*/
protected boolean cookie = false;
@@ -355,6 +355,8 @@ public class RewriteRule {
* for your decision: whenever you prefix some URLs with CGI-scripts to force them to be processed by the
* CGI-script, the chance is high that you will run into problems (or even overhead) on sub-requests. In these
* cases, use this flag.
+ * <p>
+ * Note: this flag cannot be set from the {@code rewrite.config} file and has no effect in this implementation.
*/
protected boolean nosubreq = false;
@@ -699,6 +701,8 @@ public class RewriteRule {
/**
* Set the nosubreq flag.
* @param nosubreq true to set the nosubreq flag
+ *
+ * @see #nosubreq
*/
public void setNosubreq(boolean nosubreq) {
this.nosubreq = nosubreq;
@@ -914,7 +918,7 @@ public class RewriteRule {
/**
* Get the cookie lifetime.
- * @return the cookie lifetime in minutes
+ * @return the cookie lifetime in seconds
*/
public int getCookieLifetime() {
return cookieLifetime;
@@ -922,7 +926,7 @@ public class RewriteRule {
/**
* Set the cookie lifetime.
- * @param cookieLifetime the cookie lifetime in minutes
+ * @param cookieLifetime the cookie lifetime in seconds
*/
public void setCookieLifetime(int cookieLifetime) {
this.cookieLifetime = cookieLifetime;
diff --git a/java/org/apache/catalina/webresources/AbstractFileResourceSet.java b/java/org/apache/catalina/webresources/AbstractFileResourceSet.java
index d1da47776c..eb15e05304 100644
--- a/java/org/apache/catalina/webresources/AbstractFileResourceSet.java
+++ b/java/org/apache/catalina/webresources/AbstractFileResourceSet.java
@@ -219,7 +219,7 @@ public abstract class AbstractFileResourceSet extends AbstractResourceSet {
* '\"', ':', '<' and '>' are disallowed in Windows file names and there are known problems with these
* characters when using File#getCanonicalPath().
*
- * Control characters (0x00-0x31) are not permitted and tend to be display strangely in log messages and
+ * Control characters (0x00-0x1F) are not permitted and tend to be display strangely in log messages and
* similar.
*
* '*', '?' and '|' are also not allowed and, while they are not currently known to cause other
@@ -244,11 +244,11 @@ public abstract class AbstractFileResourceSet extends AbstractResourceSet {
/**
- * Return a context-relative path, beginning with a "/", that represents the canonical version of the specified path
- * after ".." and "." elements are resolved out. If the specified path attempts to go outside the boundaries of the
- * current context (i.e. too many ".." path elements are present), return <code>null</code> instead.
+ * Return the canonical version of the specified absolute file system path after ".." and "." elements are resolved
+ * out. If the specified path attempts to go outside the file system root (i.e. too many ".." path elements are
+ * present), return <code>null</code> instead.
*
- * @param path Path to be normalized
+ * @param path Absolute path to be normalized
*/
private String normalize(String path) {
return RequestUtil.normalize(path, File.separatorChar == '\\');
diff --git a/java/org/apache/catalina/webresources/FileResourceSet.java b/java/org/apache/catalina/webresources/FileResourceSet.java
index 1642e607c6..2c94bd2498 100644
--- a/java/org/apache/catalina/webresources/FileResourceSet.java
+++ b/java/org/apache/catalina/webresources/FileResourceSet.java
@@ -43,8 +43,8 @@ public class FileResourceSet extends AbstractFileResourceSet {
* @param root The {@link WebResourceRoot} this new {@link org.apache.catalina.WebResourceSet} will be added
* to.
* @param webAppMount The path within the web application at which this {@link org.apache.catalina.WebResourceSet}
- * will be mounted. For example, to add a directory of JARs to a web application, the
- * directory would be mounted at "WEB-INF/lib/"
+ * will be mounted. For example, to serve a single file from a web application, the file
+ * would be mounted at "/sample.txt"
* @param base The absolute path to the file on the file system from which the resource will be served.
* @param internalPath The path within this new {@link org.apache.catalina.WebResourceSet} where resources will be
* served from.
diff --git a/java/org/apache/catalina/webresources/JarContents.java b/java/org/apache/catalina/webresources/JarContents.java
index c338e085b2..ea30f9e386 100644
--- a/java/org/apache/catalina/webresources/JarContents.java
+++ b/java/org/apache/catalina/webresources/JarContents.java
@@ -122,8 +122,9 @@ public final class JarContents {
* Simple hashcode of a portion of the string. Typically we would use substring, but memory and runtime speed are
* critical.
*
- * @param content Wrapping String.
- * @param startPos First character in the range.
+ * @param content Wrapping String.
+ * @param startPos First character in the range.
+ * @param hashPrime The prime used to compute the hashcode.
*
* @return hashcode of the range.
*/
@@ -144,9 +145,8 @@ public final class JarContents {
/**
* Method that identifies whether a given path <b>MIGHT</b> be in this jar. Uses the Bloom filter mechanism.
*
- * @param path Requested path. Sometimes starts with "/WEB-INF/classes".
- * @param webappRoot The value of the webapp location, which can be stripped from the path. Typically it is
- * "/WEB-INF/classes".
+ * @param path Requested path, including any internal path of the resource set.
+ * @param webappRoot The web application mount point of the resource set, which can be stripped from the path.
*
* @return Whether the prefix of the path is known to be in this jar.
*/
diff --git a/java/org/apache/catalina/webresources/JarResource.java b/java/org/apache/catalina/webresources/JarResource.java
index 1ea1952907..be78d7afa4 100644
--- a/java/org/apache/catalina/webresources/JarResource.java
+++ b/java/org/apache/catalina/webresources/JarResource.java
@@ -34,7 +34,8 @@ public class JarResource extends AbstractSingleArchiveResource {
*
* @param archiveResourceSet the archive resource set
* @param webAppPath the web application path
- * @param baseUrl the base URL
+ * @param baseUrl the base URL of the JAR file. The base URL of this resource is {@code jar:} + baseUrl +
+ * {@code !/}
* @param jarEntry the JAR entry
*/
public JarResource(AbstractArchiveResourceSet archiveResourceSet, String webAppPath, String baseUrl,
diff --git a/java/org/apache/catalina/webresources/LocalStrings.properties b/java/org/apache/catalina/webresources/LocalStrings.properties
index 0e0549e4ff..144878f196 100644
--- a/java/org/apache/catalina/webresources/LocalStrings.properties
+++ b/java/org/apache/catalina/webresources/LocalStrings.properties
@@ -47,7 +47,7 @@ classpathUrlStreamHandler.notFound=Unable to load the resource [{0}] using the t
dirResourceSet.isCaseSensitive.fail=Error trying to determine if file system at [{0}] is case sensitive so assuming it is not case sensitive
dirResourceSet.manifestFail=Failed to read manifest from [{0}]
-dirResourceSet.notDirectory=The directory specified by base and internal path [{0}]{1}[{2}] does not exist.
+dirResourceSet.notDirectory=The directory specified by base and internal path [{0}]{1}[{2}] does not exist or is not a directory.
dirResourceSet.startFail=Failed to start the resource set
dirResourceSet.writeNpe=The input stream may not be null
@@ -58,7 +58,7 @@ extractingRoot.targetFailed=Failed to create the directory [{0}] for extracted J
fileResource.getCanonicalPathFail=Unable to determine the canonical path for the resource [{0}]
fileResource.getUrlFail=Unable to determine a URL for the resource [{0}]
-fileResourceSet.notFile=The file specified by base and internal path [{0}]{1}[{2}] does not exist.
+fileResourceSet.notFile=The file specified by base and internal path [{0}]{1}[{2}] does not exist or is not a file.
fileResourceSet.startFail=Failed to start the resource set
jarResource.getInputStreamFail=Unable to obtain an InputStream for the resource [{0}] located in the JAR [{1}]
diff --git a/java/org/apache/catalina/webresources/StandardRoot.java b/java/org/apache/catalina/webresources/StandardRoot.java
index cbf5a16289..3cf39114ff 100644
--- a/java/org/apache/catalina/webresources/StandardRoot.java
+++ b/java/org/apache/catalina/webresources/StandardRoot.java
@@ -55,9 +55,9 @@ import org.apache.tomcat.util.res.StringManager;
* should be aligned with that of the associated {@link Context}.
* </p>
* <p>
- * This implementation assumes that the base attribute supplied to
+ * The base attribute supplied to
* {@link StandardRoot#createWebResourceSet( org.apache.catalina.WebResourceRoot.ResourceSetType, String, String, String, String)}
- * represents the absolute path to a file.
+ * must represent the absolute path to a file or a directory.
* </p>
*/
public class StandardRoot extends LifecycleMBeanBase implements WebResourceRoot {
@@ -218,7 +218,8 @@ public class StandardRoot extends LifecycleMBeanBase implements WebResourceRoot
* @param path The path of the resource to retrieve
* @param validate Whether to validate and normalize the path
* @param useClassLoaderResources Whether to search class loader resources
- * @return The web resource, or a non-existent resource if not found
+ * @return The web resource, or a non-existent resource if not found. May return {@code null} if the resource sets
+ * are being removed concurrently while this method is executing (during shutdown)
*/
protected WebResource getResource(String path, boolean validate, boolean useClassLoaderResources) {
if (validate) {
@@ -413,8 +414,7 @@ public class StandardRoot extends LifecycleMBeanBase implements WebResourceRoot
default -> throw new IllegalArgumentException(sm.getString("standardRoot.createUnknownType", type));
};
- // This implementation assumes that the base for all resources will be a
- // file.
+ // The base for a resource set can be either a file or a directory.
File file = new File(base);
if (file.isFile()) {
diff --git a/java/org/apache/coyote/AbstractProcessor.java b/java/org/apache/coyote/AbstractProcessor.java
index aedb030c36..a7a04c2fe4 100644
--- a/java/org/apache/coyote/AbstractProcessor.java
+++ b/java/org/apache/coyote/AbstractProcessor.java
@@ -310,7 +310,7 @@ public abstract class AbstractProcessor extends AbstractProcessorLight implement
populatePort();
return;
} else if (valueMB.getLength() == 0) {
- // Empty Host header so set sever name to empty string
+ // Empty Host header so set server name to empty string
request.serverName().setString("");
populatePort();
return;
diff --git a/java/org/apache/coyote/AbstractProtocol.java b/java/org/apache/coyote/AbstractProtocol.java
index 776cdc2aa8..cb2a1e2a49 100644
--- a/java/org/apache/coyote/AbstractProtocol.java
+++ b/java/org/apache/coyote/AbstractProtocol.java
@@ -639,7 +639,8 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler, MBeanRegis
/**
* Gets the name of this protocol instance.
- * The name will be prefix-address-port if address is non-null and prefix-port if the address is null.
+ * The name will be prefix-id if the endpoint id is non-null, prefix-address-port if address is non-null and
+ * prefix-port if the address is null.
*
* @return A name for this protocol instance that is appropriately quoted for use in an ObjectName.
*/
diff --git a/java/org/apache/coyote/ActionCode.java b/java/org/apache/coyote/ActionCode.java
index e1e71c23d4..1bf466474f 100644
--- a/java/org/apache/coyote/ActionCode.java
+++ b/java/org/apache/coyote/ActionCode.java
@@ -49,7 +49,7 @@ public enum ActionCode {
/**
* A flush() operation originated by the client ( i.e. a flush() on the servlet output stream or writer, called by a
- * servlet ). Argument is the Response.
+ * servlet ). The parameter is ignored.
*/
CLIENT_FLUSH,
@@ -171,7 +171,7 @@ public enum ActionCode {
ASYNC_IS_ASYNC,
/**
- * Callback to determine if async dispatch is in progress.
+ * Callback to determine if async processing has been started.
*/
ASYNC_IS_STARTED,
diff --git a/java/org/apache/coyote/CompressionConfig.java b/java/org/apache/coyote/CompressionConfig.java
index 537a39624e..9f038c8caa 100644
--- a/java/org/apache/coyote/CompressionConfig.java
+++ b/java/org/apache/coyote/CompressionConfig.java
@@ -63,6 +63,8 @@ public class CompressionConfig {
/**
* Returns the list of content encodings that indicate already-compressed content.
+ * <p>
+ * The order of the encodings in the returned list is not guaranteed.
*
* @return comma-separated list of encoding names
*/
@@ -76,7 +78,7 @@ public class CompressionConfig {
* When content is already encoded with one of these encodings, compression will not be applied
* to prevent double compression.
*
- * @param encodings Comma-separated list of encoding names (e.g., "gzip,br.dflate")
+ * @param encodings Comma-separated list of encoding names (e.g., "gzip,br,deflate")
*/
public void setNoCompressionEncodings(String encodings) {
Set<String> newEncodings = new HashSet<>();
diff --git a/java/org/apache/coyote/NonPipeliningProcessor.java b/java/org/apache/coyote/NonPipeliningProcessor.java
index a6e8759a57..4dbf0d4688 100644
--- a/java/org/apache/coyote/NonPipeliningProcessor.java
+++ b/java/org/apache/coyote/NonPipeliningProcessor.java
@@ -17,8 +17,8 @@
package org.apache.coyote;
/**
- * Marker interface used to indicate that the {@link Processor} does not implement pipe-lining of requests (e.g.
- * HTTP/1.1 supports pipe-lining whereas HTTP/2 does not) which may enable some components to clear references sooner to
+ * Marker interface used to indicate that the {@link Processor} does not implement pipelining of requests (e.g.
+ * HTTP/1.1 supports pipelining whereas HTTP/2 does not) which may enable some components to clear references sooner to
* aid GC.
*/
public interface NonPipeliningProcessor extends Processor {
diff --git a/java/org/apache/coyote/ProtocolHandler.java b/java/org/apache/coyote/ProtocolHandler.java
index 9798de379e..cad042776c 100644
--- a/java/org/apache/coyote/ProtocolHandler.java
+++ b/java/org/apache/coyote/ProtocolHandler.java
@@ -233,6 +233,7 @@ public interface ProtocolHandler {
* @throws InvocationTargetException Exception occurred
* @throws NoSuchMethodException Exception occurred
* @throws SecurityException Exception occurred
+ * @throws ClassCastException Specified protocol does not implement {@link ProtocolHandler}
*/
static ProtocolHandler create(String protocol)
throws ClassNotFoundException, InstantiationException, IllegalAccessException, IllegalArgumentException,
diff --git a/java/org/apache/coyote/RequestGroupInfo.java b/java/org/apache/coyote/RequestGroupInfo.java
index eb20a424bf..67f9042e45 100644
--- a/java/org/apache/coyote/RequestGroupInfo.java
+++ b/java/org/apache/coyote/RequestGroupInfo.java
@@ -155,11 +155,11 @@ public class RequestGroupInfo extends BaseModelMBean {
* @return the error count
*/
public synchronized int getErrorCount() {
- int requestCount = deadErrorCount;
+ int errorCount = deadErrorCount;
for (RequestInfo rp : processors) {
- requestCount += rp.getErrorCount();
+ errorCount += rp.getErrorCount();
}
- return requestCount;
+ return errorCount;
}
/**
diff --git a/java/org/apache/coyote/UpgradeProtocol.java b/java/org/apache/coyote/UpgradeProtocol.java
index 2d79ebfd6e..723047591c 100644
--- a/java/org/apache/coyote/UpgradeProtocol.java
+++ b/java/org/apache/coyote/UpgradeProtocol.java
@@ -97,7 +97,7 @@ public interface UpgradeProtocol {
/**
- * Configure the HTTP/1.1 protocol that this UpgradeProcotol is nested under. Connections passed to this
+ * Configure the HTTP/1.1 protocol that this UpgradeProtocol is nested under. Connections passed to this
* UpgradeProtocol via HTTP upgrade will have been initially handled by this HTTP/1.1 protocol implementation.
* <p>
* The default implementation is a NO-OP.
diff --git a/java/org/apache/coyote/ajp/AbstractAjpProtocol.java b/java/org/apache/coyote/ajp/AbstractAjpProtocol.java
index ad8f34b037..8302f56ef4 100644
--- a/java/org/apache/coyote/ajp/AbstractAjpProtocol.java
+++ b/java/org/apache/coyote/ajp/AbstractAjpProtocol.java
@@ -29,9 +29,9 @@ import org.apache.tomcat.util.net.SocketWrapperBase;
import org.apache.tomcat.util.res.StringManager;
/**
- * This the base implementation for the AJP protocol handlers. Implementations typically extend this base class rather
- * than implement {@link org.apache.coyote.ProtocolHandler}. All of the implementations that ship with Tomcat are
- * implemented this way.
+ * This is the base implementation for the AJP protocol handlers. Implementations typically extend this base class
+ * rather than implement {@link org.apache.coyote.ProtocolHandler}. All of the implementations that ship with Tomcat
+ * are implemented this way.
*
* @param <S> The type of socket used by the implementation
*/
diff --git a/java/org/apache/coyote/ajp/AjpMessage.java b/java/org/apache/coyote/ajp/AjpMessage.java
index 590b5d30fa..b452498b1d 100644
--- a/java/org/apache/coyote/ajp/AjpMessage.java
+++ b/java/org/apache/coyote/ajp/AjpMessage.java
@@ -292,7 +292,8 @@ public class AjpMessage {
/**
- * Read a null-terminated string of bytes from the packet.
+ * Read a null-terminated string of bytes from the packet. A length of {@code 0xFFFF} indicates that there is no
+ * value: the {@code MessageBytes} is recycled and the read position is not advanced.
*
* @param mb The MessageBytes to populate with the read bytes
*/
diff --git a/java/org/apache/coyote/ajp/AjpNioProtocol.java b/java/org/apache/coyote/ajp/AjpNioProtocol.java
index 04a5e375a6..be1fb622a6 100644
--- a/java/org/apache/coyote/ajp/AjpNioProtocol.java
+++ b/java/org/apache/coyote/ajp/AjpNioProtocol.java
@@ -22,7 +22,7 @@ import org.apache.tomcat.util.net.NioChannel;
import org.apache.tomcat.util.net.NioEndpoint;
/**
- * This the NIO based protocol handler implementation for AJP.
+ * This is the NIO based protocol handler implementation for AJP.
*/
public class AjpNioProtocol extends AbstractAjpProtocol<NioChannel> {
diff --git a/java/org/apache/coyote/ajp/AjpProcessor.java b/java/org/apache/coyote/ajp/AjpProcessor.java
index e718c5ad2c..25d341d458 100644
--- a/java/org/apache/coyote/ajp/AjpProcessor.java
+++ b/java/org/apache/coyote/ajp/AjpProcessor.java
@@ -178,8 +178,8 @@ public class AjpProcessor extends AbstractProcessor {
/**
- * Location of next write of the response message (used with non-blocking writes when the message may not be written
- * in a single write). A value of -1 indicates that no message has been written to the buffer.
+ * Intended to hold the location of the next write of the response message when non-blocking writes do not write
+ * the message in a single write. Always -1 in the current implementation as the write path does not update it.
*/
private int responseMsgPos = -1;
diff --git a/java/org/apache/coyote/http11/Http11Processor.java b/java/org/apache/coyote/http11/Http11Processor.java
index 14743ba1ac..874caa2250 100644
--- a/java/org/apache/coyote/http11/Http11Processor.java
+++ b/java/org/apache/coyote/http11/Http11Processor.java
@@ -420,7 +420,7 @@ public class Http11Processor extends AbstractProcessor {
response.reset();
response.setStatus(500);
setErrorState(ErrorState.CLOSE_CLEAN, e);
- response.setHeader("Connection", "close"); // TODO: Remove
+ response.setHeader("Connection", "close");
}
} catch (Throwable t) {
ExceptionUtils.handleThrowable(t);
diff --git a/java/org/apache/coyote/http11/upgrade/LocalStrings.properties b/java/org/apache/coyote/http11/upgrade/LocalStrings.properties
index 2f0516f9ba..bf50689452 100644
--- a/java/org/apache/coyote/http11/upgrade/LocalStrings.properties
+++ b/java/org/apache/coyote/http11/upgrade/LocalStrings.properties
@@ -33,4 +33,4 @@ upgradeProcessor.isCloseFail=Failed to close input stream associated with upgrad
upgradeProcessor.osCloseFail=Failed to close output stream associated with upgraded connection
upgradeProcessor.requiredClose=Closing upgraded connection due to closeRequired state of streams: Input [{0}], Output [{1}]
upgradeProcessor.stop=Closing upgraded connection as incoming socket status was STOP
-upgradeProcessor.unexpectedState=Closing upgraded connection unexpectedly as incoming socket status was [{0}]
+upgradeProcessor.unexpectedState=Closing upgraded connection unexpectedly
diff --git a/java/org/apache/coyote/http11/upgrade/UpgradeServletInputStream.java b/java/org/apache/coyote/http11/upgrade/UpgradeServletInputStream.java
index 64e3ae0022..adc1fc59d0 100644
--- a/java/org/apache/coyote/http11/upgrade/UpgradeServletInputStream.java
+++ b/java/org/apache/coyote/http11/upgrade/UpgradeServletInputStream.java
@@ -136,7 +136,8 @@ public class UpgradeServletInputStream extends ServletInputStream {
this.listener = listener;
- // Container is responsible for first call to onDataAvailable().
+ // The first call to onDataAvailable() will be triggered by the poller
+ // once read interest is registered.
Request request = processor.getRequest();
if (request != null && request.isRequestThread()) {
processor.addDispatch(DispatchType.NON_BLOCKING_READ);
diff --git a/java/org/apache/coyote/http11/upgrade/UpgradeServletOutputStream.java b/java/org/apache/coyote/http11/upgrade/UpgradeServletOutputStream.java
index e08e5cb2f3..93240fcded 100644
--- a/java/org/apache/coyote/http11/upgrade/UpgradeServletOutputStream.java
+++ b/java/org/apache/coyote/http11/upgrade/UpgradeServletOutputStream.java
@@ -149,7 +149,8 @@ public class UpgradeServletOutputStream extends ServletOutputStream {
throw new IllegalStateException(sm.getString("upgrade.sos.write.closed"));
}
this.listener = listener;
- // Container is responsible for first call to onWritePossible().
+ // The first call to onWritePossible() will be triggered by the poller
+ // once write interest is registered.
synchronized (registeredLock) {
registered = true;
Request request = processor.getRequest();
diff --git a/java/org/apache/coyote/http2/AbstractStream.java b/java/org/apache/coyote/http2/AbstractStream.java
index bb0f0d1bc1..71d7c26cf6 100644
--- a/java/org/apache/coyote/http2/AbstractStream.java
+++ b/java/org/apache/coyote/http2/AbstractStream.java
@@ -154,7 +154,7 @@ abstract class AbstractStream {
windowAllocationLock.lock();
try {
// No need for overflow protection here. Decrement can never be larger
- // the Integer.MAX_VALUE and once windowSize goes negative no further
+ // than the Integer.MAX_VALUE and once windowSize goes negative no further
// decrements are permitted
windowSize -= decrement;
if (log.isTraceEnabled()) {
diff --git a/java/org/apache/coyote/http2/ConnectionSettingsBase.java b/java/org/apache/coyote/http2/ConnectionSettingsBase.java
index 76382100b0..1d5fd9c687 100644
--- a/java/org/apache/coyote/http2/ConnectionSettingsBase.java
+++ b/java/org/apache/coyote/http2/ConnectionSettingsBase.java
@@ -34,7 +34,7 @@ abstract class ConnectionSettingsBase<T extends Throwable> {
static final int MAX_WINDOW_SIZE = (1 << 31) - 1;
static final int MIN_MAX_FRAME_SIZE = 1 << 14;
static final int MAX_MAX_FRAME_SIZE = (1 << 24) - 1;
- static final long UNLIMITED = ((long) 1 << 32); // Use the maximum possible
+ static final long UNLIMITED = ((long) 1 << 32); // Internal "no limit" sentinel; not a valid 32-bit SETTINGS value
static final int MAX_HEADER_TABLE_SIZE = 1 << 16;
// Defaults (defined by the specification)
@@ -102,6 +102,9 @@ abstract class ConnectionSettingsBase<T extends Throwable> {
/**
* Specify a new value for setting with the option to force the change to take effect immediately rather than
* waiting until an {@code ACK} is received.
+ * <p>
+ * The default implementation applies the value to the current settings and ignores {@code force}. The
+ * {@link ConnectionSettingsLocal} override honors {@code force}.
*
* @param setting The setting to update
* @param value The new value for the setting
diff --git a/java/org/apache/coyote/http2/ConnectionSettingsLocal.java b/java/org/apache/coyote/http2/ConnectionSettingsLocal.java
index 5ceec8ece1..00ba630465 100644
--- a/java/org/apache/coyote/http2/ConnectionSettingsLocal.java
+++ b/java/org/apache/coyote/http2/ConnectionSettingsLocal.java
@@ -23,8 +23,9 @@ import java.util.Map;
* server. There will be a delay between calling a setter and the setting taking effect at the client. When a setter is
* called, the new value is added to the set of pending settings. Once the ACK is received, the new value is moved to
* the current settings. While waiting for the ACK, the getters will return the most lenient / generous / relaxed of the
- * current setting and the pending setting. This class does not validate the values passed to the setters. If an invalid
- * value is used the client will respond (almost certainly by closing the connection) as defined in the HTTP/2
+ * current setting and the pending setting. Values passed to the setters are validated by the base class, except for
+ * {@code MAX_CONCURRENT_STREAMS} and {@code MAX_HEADER_LIST_SIZE}. If an invalid value is used the client will respond
+ * (almost certainly by closing the connection) as defined in the HTTP/2
* specification.
*/
class ConnectionSettingsLocal extends ConnectionSettingsBase<IllegalArgumentException> {
diff --git a/java/org/apache/coyote/http2/HPackHuffman.java b/java/org/apache/coyote/http2/HPackHuffman.java
index f872ec1667..03011a251d 100644
--- a/java/org/apache/coyote/http2/HPackHuffman.java
+++ b/java/org/apache/coyote/http2/HPackHuffman.java
@@ -42,10 +42,11 @@ public class HPackHuffman {
private static final HuffmanCode[] HUFFMAN_CODES;
/**
- * array based tree representation of a huffman code.
+ * Array based tree representation of the Huffman codes.
* <p/>
- * the high two bytes corresponds to the tree node if the bit is set, and the low two bytes for if it is clear if
- * the high bit is set it is a terminal node, otherwise it contains the next node position.
+ * Each entry consists of two 16-bit halves: the high half is the branch to follow when the current bit is 1 and
+ * the low half is the branch to follow when the current bit is 0. Within each half, the top bit flags a terminal
+ * node and the remaining 15 bits hold either the symbol to append or the position of the next node in this array.
*/
private static final int[] DECODING_TABLE;
diff --git a/java/org/apache/coyote/http2/HpackDecoder.java b/java/org/apache/coyote/http2/HpackDecoder.java
index 5e7fd071bc..bf8b34d77a 100644
--- a/java/org/apache/coyote/http2/HpackDecoder.java
+++ b/java/org/apache/coyote/http2/HpackDecoder.java
@@ -287,7 +287,8 @@ public class HpackDecoder {
int dynamicIndex = index - Hpack.STATIC_TABLE_LENGTH;
// The index is one based, but our table is zero based
// Also, because of our ring buffer set up, the indexes are reversed
- // index = 1 is at position firstSlotPosition + filledSlots
+ // Dynamic index 1 (the most recently added entry) is at position
+ // (firstSlotPosition + filledTableSlots - 1) % headerTable.length
if (dynamicIndex < 1 || dynamicIndex > filledTableSlots) {
throw new HpackException(sm.getString("hpackdecoder.headerTableIndexInvalid", Integer.valueOf(index),
Integer.valueOf(Hpack.STATIC_TABLE_LENGTH), Integer.valueOf(filledTableSlots)));
diff --git a/java/org/apache/coyote/http2/Http2Protocol.java b/java/org/apache/coyote/http2/Http2Protocol.java
index 9f1fdaea8f..b384e69dd6 100644
--- a/java/org/apache/coyote/http2/Http2Protocol.java
+++ b/java/org/apache/coyote/http2/Http2Protocol.java
@@ -206,7 +206,7 @@ public class Http2Protocol implements UpgradeProtocol {
/**
- * Configure whether HTTP/2 streams atr allowed to provide a scheme that is inconsistent with the transport over
+ * Configure whether HTTP/2 streams are allowed to provide a scheme that is inconsistent with the transport over
* which the stream was received
*
* @param allowSchemeMismatch {@code true} if a mismatched scheme is permitted, otherwise {@code false}
diff --git a/java/org/apache/coyote/http2/Http2UpgradeHandler.java b/java/org/apache/coyote/http2/Http2UpgradeHandler.java
index aa59511fe2..a29af4b1c8 100644
--- a/java/org/apache/coyote/http2/Http2UpgradeHandler.java
+++ b/java/org/apache/coyote/http2/Http2UpgradeHandler.java
@@ -66,7 +66,9 @@ import org.apache.tomcat.util.res.StringManager;
* Note:
* <ul>
* <li>You will need to nest a <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" /> element
- * inside a TLS enabled Connector element in server.xml to enable HTTP/2 support.</li>
+ * inside a Connector element in server.xml to enable HTTP/2 support. For a TLS enabled Connector, HTTP/2 connections
+ * are negotiated using ALPN (h2). For a Connector that is not TLS enabled, HTTP/2 connections use the cleartext
+ * (h2c) mechanism.</li>
* </ul>
*/
class Http2UpgradeHandler extends AbstractStream implements InternalHttpUpgradeHandler, Input, Output {
diff --git a/java/org/apache/coyote/http2/StreamProcessor.java b/java/org/apache/coyote/http2/StreamProcessor.java
index e4da15100f..279ac32cfc 100644
--- a/java/org/apache/coyote/http2/StreamProcessor.java
+++ b/java/org/apache/coyote/http2/StreamProcessor.java
@@ -383,7 +383,7 @@ class StreamProcessor extends AbstractProcessor implements NonPipeliningProcesso
/*
* Dispatch on new thread. Firstly, this avoids a deadlock on the SocketWrapper as Streams being processed
* by container threads lock the SocketProcessor before they lock the SocketWrapper which is the opposite
- * order to container threads processing via Http2UpgrageHandler. Secondly, this code executes after a
+ * order to container threads processing via Http2UpgradeHandler. Secondly, this code executes after a
* Window update has released one or more Streams. By dispatching each Stream to a dedicated thread, those
* Streams may progress concurrently.
*/
@@ -414,7 +414,7 @@ class StreamProcessor extends AbstractProcessor implements NonPipeliningProcesso
public final void recycle() {
// StreamProcessor instances are not re-used.
- // Calling removeRequestProcessor even though the RequestProcesser was
+ // Calling removeRequestProcessor even though the RequestProcessor was
// never added will add the values from the RequestProcessor to the
// running total for the GlobalRequestProcessor
RequestGroupInfo global = handler.getProtocol().getGlobal();
diff --git a/java/org/apache/coyote/http2/StreamStateMachine.java b/java/org/apache/coyote/http2/StreamStateMachine.java
index b8c4e2fe63..dd4220d87d 100644
--- a/java/org/apache/coyote/http2/StreamStateMachine.java
+++ b/java/org/apache/coyote/http2/StreamStateMachine.java
@@ -25,10 +25,12 @@ import org.apache.juli.logging.LogFactory;
import org.apache.tomcat.util.res.StringManager;
/**
- * See <a href="https://tools.ietf.org/html/rfc7540#section-5.1">state diagram</a> in RFC 7540. <br>
+ * See <a href="https://www.rfc-editor.org/rfc/rfc9113#section-5.1">section 5.1</a> of RFC 9113 for the state
+ * diagram. <br>
* The following additions are supported by this state machine:
* <ul>
- * <li>differentiate between closed (normal) and closed caused by reset</li>
+ * <li>the closed state is split into separate states that differentiate between a normal close and a close caused by
+ * a reset, and between which direction sent the final frame</li>
* </ul>
*/
class StreamStateMachine {
diff --git a/java/org/apache/coyote/http2/WindowAllocationManager.java b/java/org/apache/coyote/http2/WindowAllocationManager.java
index cbe6393564..3d69783663 100644
--- a/java/org/apache/coyote/http2/WindowAllocationManager.java
+++ b/java/org/apache/coyote/http2/WindowAllocationManager.java
@@ -34,7 +34,7 @@ import org.apache.tomcat.util.res.StringManager;
* triggered.
* <p>
* With the implementation at the time of writing, it is not possible for a stream to receive an unexpected connection
- * notification as these are only issues to streams in the backlog and a stream must be waiting for a connection
+ * notification as these are only issued to streams in the backlog and a stream must be waiting for a connection
* allocation in order to be placed on the backlog. However, as a precaution, this class protects against unexpected
* connection notifications.
* <p>
diff --git a/java/org/apache/el/MethodExpressionImpl.java b/java/org/apache/el/MethodExpressionImpl.java
index f1ca189432..8e0b7ed897 100644
--- a/java/org/apache/el/MethodExpressionImpl.java
+++ b/java/org/apache/el/MethodExpressionImpl.java
@@ -42,8 +42,9 @@ import org.apache.el.util.ReflectionUtil;
* <p>
* The {@link jakarta.el.ExpressionFactory#createMethodExpression} method can be used to parse an expression string and
* return a concrete instance of <code>MethodExpression</code> that encapsulates the parsed expression. The
- * {@link FunctionMapper} is used at parse time, not evaluation time, so one is not needed to evaluate an expression
- * using this class. However, the {@link ELContext} is needed at evaluation time.
+ * {@link FunctionMapper} is used at parse time. This class retains the {@link FunctionMapper} used at parse time and
+ * uses it to resolve functions at evaluation time, so the {@link ELContext} used for evaluation does not need to have
+ * a {@link FunctionMapper} configured. However, the {@link ELContext} is needed at evaluation time.
* </p>
* <p>
* The {@link #getMethodInfo} and {@link #invoke} methods will evaluate the expression each time they are called. The
@@ -122,7 +123,7 @@ public final class MethodExpressionImpl extends MethodExpression implements Exte
*
* @return <code>true</code> if <code>obj</code> equals this <code>Expression</code>; <code>false</code> otherwise.
*
- * @see java.util.Hashtable
+ * @see java.util.HashMap
* @see java.lang.Object#equals(java.lang.Object)
*/
@Override
@@ -201,7 +202,7 @@ public final class MethodExpressionImpl extends MethodExpression implements Exte
* @return The hash code for this <code>Expression</code>.
*
* @see #equals
- * @see java.util.Hashtable
+ * @see java.util.HashMap
* @see java.lang.Object#hashCode()
*/
@Override
diff --git a/java/org/apache/el/ValueExpressionImpl.java b/java/org/apache/el/ValueExpressionImpl.java
index 78f3aa8f38..67fc44aca1 100644
--- a/java/org/apache/el/ValueExpressionImpl.java
+++ b/java/org/apache/el/ValueExpressionImpl.java
@@ -50,8 +50,9 @@ import org.apache.el.util.ReflectionUtil;
* <p>
* The {@link jakarta.el.ExpressionFactory#createValueExpression} method can be used to parse an expression string and
* return a concrete instance of <code>ValueExpression</code> that encapsulates the parsed expression. The
- * {@link FunctionMapper} is used at parse time, not evaluation time, so one is not needed to evaluate an expression
- * using this class. However, the {@link ELContext} is needed at evaluation time.
+ * {@link FunctionMapper} is used at parse time. This class retains the {@link FunctionMapper} used at parse time and
+ * uses it to resolve functions at evaluation time, so the {@link ELContext} used for evaluation does not need to have
+ * a {@link FunctionMapper} configured. However, the {@link ELContext} is needed at evaluation time.
* </p>
* <p>
* The {@link #getValue}, {@link #setValue}, {@link #isReadOnly} and {@link #getType} methods will evaluate the
@@ -120,18 +121,21 @@ public final class ValueExpressionImpl extends ValueExpression implements Extern
return this.getNode().equals(((ValueExpressionImpl) obj).getNode());
}
+ /**
+ * Returns the type the result of the expression will be coerced to after evaluation.
+ *
+ * @return the <code>expectedType</code> passed to the <code>ExpressionFactory.createValueExpression</code> method
+ * that created this <code>ValueExpression</code>.
+ */
@Override
public Class<?> getExpectedType() {
return this.expectedType;
}
/**
- * Returns the type the result of the expression will be coerced to after evaluation.
- *
- * @return the <code>expectedType</code> passed to the <code>ExpressionFactory.createValueExpression</code> method
- * that created this <code>ValueExpression</code>.
+ * Returns the expression string.
*
- * @see jakarta.el.Expression#getExpressionString()
+ * @return the expression string
*/
@Override
public String getExpressionString() {
diff --git a/java/org/apache/el/lang/ELSupport.java b/java/org/apache/el/lang/ELSupport.java
index 20665e002d..6ca2e07a36 100644
--- a/java/org/apache/el/lang/ELSupport.java
+++ b/java/org/apache/el/lang/ELSupport.java
@@ -83,8 +83,9 @@ public class ELSupport {
*
* @return -1, 0, or 1 if this object is less than, equal to, or greater than val.
*
- * @throws ELException if neither object is Comparable
- * @throws ClassCastException if the objects are not mutually comparable
+ * @throws ELException if neither object is Comparable
+ * @throws ClassCastException if the objects are not mutually comparable
+ * @throws NullPointerException if either object is null
*/
public static int compare(final ELContext ctx, final Object obj0, final Object obj1) throws ELException {
if (obj0 == obj1 || equals(ctx, obj0, obj1)) {
@@ -141,9 +142,12 @@ public class ELSupport {
* <p>
* If either object is null, return false.
* <p>
+ * If either object is a BigDecimal, Double(Float), BigInteger or Long(Integer, Short, Byte, Character), coerce
+ * both to the corresponding numeric type and check equality.
+ * <p>
* If either object is Boolean, coerce both to Boolean and check equality.
* <p>
- * Similarly for Enum, String, BigDecimal, Double(Float), Long(Integer, Short, Byte, Character)
+ * Similarly for Enum, String and date types (TemporalAccessor, Clock, java.util.Date or java.sql.Timestamp)
* <p>
* Otherwise default to using Object.equals().
*
diff --git a/java/org/apache/el/lang/FunctionMapperFactory.java b/java/org/apache/el/lang/FunctionMapperFactory.java
index d47977a7e5..cf249585ba 100644
--- a/java/org/apache/el/lang/FunctionMapperFactory.java
+++ b/java/org/apache/el/lang/FunctionMapperFactory.java
@@ -24,7 +24,7 @@ import org.apache.el.util.MessageFactory;
/**
* Factory that wraps a target FunctionMapper, capturing all function mappings
- * so that an immutable snapshot can be created.
+ * so that a point-in-time snapshot can be created.
*/
public class FunctionMapperFactory extends FunctionMapper {
@@ -73,7 +73,9 @@ public class FunctionMapperFactory extends FunctionMapper {
/**
- * Creates an immutable snapshot of all function mappings captured so far.
+ * Creates a snapshot of all function mappings captured so far.
+ * <p>
+ * The returned mapper is a point-in-time capture; it is mutable and may be modified after it is returned.
*
* @return The captured function mappings as a FunctionMapper
*/
diff --git a/java/org/apache/el/lang/VariableMapperFactory.java b/java/org/apache/el/lang/VariableMapperFactory.java
index 26e20135a3..b349ee6ece 100644
--- a/java/org/apache/el/lang/VariableMapperFactory.java
+++ b/java/org/apache/el/lang/VariableMapperFactory.java
@@ -31,7 +31,7 @@ public class VariableMapperFactory extends VariableMapper {
*/
private final VariableMapper target;
/**
- * The momento mapper that tracks resolved variables.
+ * The memento mapper that tracks resolved variables.
*/
private VariableMapper momento;
diff --git a/java/org/apache/el/parser/AstAbstractEmpty.java b/java/org/apache/el/parser/AstAbstractEmpty.java
index f4f3442b52..7509cae71c 100644
--- a/java/org/apache/el/parser/AstAbstractEmpty.java
+++ b/java/org/apache/el/parser/AstAbstractEmpty.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/* Generated By:JJTree: Do not edit this line. AstEmpty.java */
+/* Generated By:JJTree: Do not edit this line. AstAbstractEmpty.java */
package org.apache.el.parser;
import java.util.Collection;
diff --git a/java/org/apache/el/parser/AstConcatenation.java b/java/org/apache/el/parser/AstConcatenation.java
index d93f82dae3..d63fc5ec97 100644
--- a/java/org/apache/el/parser/AstConcatenation.java
+++ b/java/org/apache/el/parser/AstConcatenation.java
@@ -57,7 +57,7 @@ public class AstConcatenation extends SimpleNode {
}
}
- // Coerce the two child nodes to string and then concatenate
+ // Coerce the two values to string and then concatenate
String s1 = ELSupport.coerceToString(ctx, obj0);
String s2 = ELSupport.coerceToString(ctx, obj1);
return s1 + s2;
diff --git a/java/org/apache/el/parser/AstInteger.java b/java/org/apache/el/parser/AstInteger.java
index 6c5172ab47..d25ccdcc84 100644
--- a/java/org/apache/el/parser/AstInteger.java
+++ b/java/org/apache/el/parser/AstInteger.java
@@ -41,9 +41,9 @@ public final class AstInteger extends SimpleNode {
this.number = new BigInteger(this.image);
}
} catch (ArithmeticException | NumberFormatException e) {
- // Too big for BigInteger.
- // Catch NumberFormatException as well here just in case the
- // parser provides invalid input.
+ // The parser only produces digit-only images for which
+ // new BigInteger(String) cannot overflow, so this catch is
+ // purely defensive.
throw new ELException(e);
}
}
diff --git a/java/org/apache/el/parser/AstMethodParameters.java b/java/org/apache/el/parser/AstMethodParameters.java
index f12cd2f9c9..2e85e85134 100644
--- a/java/org/apache/el/parser/AstMethodParameters.java
+++ b/java/org/apache/el/parser/AstMethodParameters.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/* Generated By:JJTree: Do not edit this line. AstDotSuffix.java */
+/* Generated By:JJTree: Do not edit this line. AstMethodParameters.java */
package org.apache.el.parser;
import org.apache.el.lang.EvaluationContext;
diff --git a/java/org/apache/el/parser/AstNotEmpty.java b/java/org/apache/el/parser/AstNotEmpty.java
index 0066c07afb..aa3657226a 100644
--- a/java/org/apache/el/parser/AstNotEmpty.java
+++ b/java/org/apache/el/parser/AstNotEmpty.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/* Generated By:JJTree: Do not edit this line. AstEmpty.java */
+/* Generated By:JJTree: Do not edit this line. AstNotEmpty.java */
package org.apache.el.parser;
public final class AstNotEmpty extends AstAbstractEmpty {
diff --git a/java/org/apache/el/parser/AstNullCoalescing.java b/java/org/apache/el/parser/AstNullCoalescing.java
index 98a010e32a..6d0a3437c5 100644
--- a/java/org/apache/el/parser/AstNullCoalescing.java
+++ b/java/org/apache/el/parser/AstNullCoalescing.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/* Generated By:JJTree: Do not edit this line. AstNullCoalescing.java Version 7.0 */
+/* Generated By:JJTree: Do not edit this line. AstNullCoalescing.java */
/* JavaCCOptions:MULTI=true,NODE_USES_PARSER=false,VISITOR=false,TRACK_TOKENS=false,NODE_PREFIX=Ast,NODE_EXTENDS=,NODE_FACTORY=,SUPPORT_CLASS_VISIBILITY_PUBLIC=true */
package org.apache.el.parser;
diff --git a/java/org/apache/el/parser/ELParser.java b/java/org/apache/el/parser/ELParser.java
index d4f679a85f..58c8b71587 100644
--- a/java/org/apache/el/parser/ELParser.java
+++ b/java/org/apache/el/parser/ELParser.java
@@ -1036,7 +1036,8 @@ public class ELParser/* @bgen(jjtree) */ implements ELParserTreeConstants, ELPar
}
/*
- * Compare For a bunch of them, then +=
+ * Compare a Concatenation operand against zero or more relational
+ * operators (<, >, <=, >=, lt, gt, le, ge).
*/
final public void Compare() throws ParseException {
Concatenation();
diff --git a/java/org/apache/el/parser/SimpleCharStream.java b/java/org/apache/el/parser/SimpleCharStream.java
index 8f824e7bcc..d8eda8b003 100644
--- a/java/org/apache/el/parser/SimpleCharStream.java
+++ b/java/org/apache/el/parser/SimpleCharStream.java
@@ -3,8 +3,8 @@
package org.apache.el.parser;
/**
- * An implementation of interface CharStream, where the stream is assumed to contain only ASCII characters (without
- * unicode processing).
+ * A simple character stream implementation used by the EL parser. The stream is char[]-based and fully supports
+ * 16-bit characters.
*/
@SuppressWarnings("all") // Ignore warnings in generated code
diff --git a/java/org/apache/el/parser/TokenMgrError.java b/java/org/apache/el/parser/TokenMgrError.java
index b608976f08..6c14c61f4e 100644
--- a/java/org/apache/el/parser/TokenMgrError.java
+++ b/java/org/apache/el/parser/TokenMgrError.java
@@ -32,7 +32,8 @@ public class TokenMgrError extends Error {
public static final int INVALID_LEXICAL_STATE = 2;
/**
- * Detected (and bailed out of) an infinite loop in the token manager.
+ * Boilerplate reason code from the JavaCC token manager template. This generated token manager performs no loop
+ * detection and never throws with this reason.
*/
public static final int LOOP_DETECTED = 3;
diff --git a/java/org/apache/el/stream/Stream.java b/java/org/apache/el/stream/Stream.java
index 24f20bf043..2a0be487e7 100644
--- a/java/org/apache/el/stream/Stream.java
+++ b/java/org/apache/el/stream/Stream.java
@@ -444,7 +444,8 @@ public class Stream {
/**
- * Calculates the average of all numeric elements in the stream.
+ * Calculates the average of all elements in the stream. Elements are coerced to a numeric type; a non-convertible
+ * element results in an {@code ELException}.
*
* @return an Optional containing the average, or empty if the stream is empty
*/
@@ -466,7 +467,8 @@ public class Stream {
/**
- * Returns the sum of all numeric elements in the stream.
+ * Returns the sum of all elements in the stream. Elements are coerced to a numeric type; a non-convertible
+ * element results in an {@code ELException}.
*
* @return the sum of all elements
*/
diff --git a/java/org/apache/el/util/ConcurrentCache.java b/java/org/apache/el/util/ConcurrentCache.java
index 57921c2f17..49b6d98300 100644
--- a/java/org/apache/el/util/ConcurrentCache.java
+++ b/java/org/apache/el/util/ConcurrentCache.java
@@ -22,7 +22,7 @@ import java.util.concurrent.ConcurrentHashMap;
/**
* A thread-safe cache that uses an eden space backed by a {@link ConcurrentHashMap}
- * and a long-term space backed by a {@link WeakHashMap}. When the eden space exceeds
+ * and a long-term space backed by a {@link WeakHashMap}. When the eden space reaches
* the configured size, its contents are promoted to the long-term space.
*
* @param <K> the key type
diff --git a/java/org/apache/el/util/ReflectionUtil.java b/java/org/apache/el/util/ReflectionUtil.java
index 5458d937b8..e0c09d0dd7 100644
--- a/java/org/apache/el/util/ReflectionUtil.java
+++ b/java/org/apache/el/util/ReflectionUtil.java
@@ -148,7 +148,7 @@ public class ReflectionUtil {
* @throws MethodNotFoundException If a method cannot be found that matches the given criteria
*/
/*
- * This class duplicates code in jakarta.el.Util. When making changes keep the code in sync.
+ * This method duplicates code in jakarta.el.Util. When making changes keep the code in sync.
*/
@SuppressWarnings("null")
public static Method getMethod(EvaluationContext ctx, Object base, Object property, Class<?>[] paramTypes,
@@ -348,7 +348,7 @@ public class ReflectionUtil {
}
/*
- * This class duplicates code in jakarta.el.Util. When making changes keep the code in sync.
+ * This method duplicates code in jakarta.el.Util. When making changes keep the code in sync.
*/
private static Method resolveAmbiguousMethod(Set<Method> candidates, Class<?>[] paramTypes) {
// Identify which parameter isn't an exact match
@@ -412,7 +412,7 @@ public class ReflectionUtil {
/*
- * This class duplicates code in jakarta.el.Util. When making changes keep the code in sync.
+ * This method duplicates code in jakarta.el.Util. When making changes keep the code in sync.
*/
private static boolean isAssignableFrom(Class<?> src, Class<?> target) {
// src will always be an object
@@ -449,7 +449,7 @@ public class ReflectionUtil {
/*
- * This class duplicates code in jakarta.el.Util. When making changes keep the code in sync.
+ * This method duplicates code in jakarta.el.Util. When making changes keep the code in sync.
*/
private static boolean isCoercibleFrom(EvaluationContext ctx, Object src, Class<?> target) {
// TODO: This isn't pretty but it works. Significant refactoring would be required to avoid the exception.
@@ -463,7 +463,7 @@ public class ReflectionUtil {
/*
- * This class duplicates code in jakarta.el.Util. When making changes keep the code in sync.
+ * This method duplicates code in jakarta.el.Util. When making changes keep the code in sync.
*/
private static Method getMethod(Class<?> type, Object base, Method m) {
if (m == null || (Modifier.isPublic(type.getModifiers()) &&
diff --git a/java/org/apache/el/util/Validation.java b/java/org/apache/el/util/Validation.java
index 94cc529fbe..db3f43197d 100644
--- a/java/org/apache/el/util/Validation.java
+++ b/java/org/apache/el/util/Validation.java
@@ -41,7 +41,7 @@ public class Validation {
}
/**
- * Test whether a string is a Java identifier. Note that the behaviour of this method depend on the system property
+ * Test whether a string is a Java identifier. Note that the behaviour of this method depends on the system property
* {@code org.apache.el.parser.SKIP_IDENTIFIER_CHECK}
*
* @param key The string to test
diff --git a/java/org/apache/jasper/JspC.java b/java/org/apache/jasper/JspC.java
index 995772c2e0..0a8611510f 100644
--- a/java/org/apache/jasper/JspC.java
+++ b/java/org/apache/jasper/JspC.java
@@ -83,7 +83,7 @@ import org.xml.sax.SAXException;
* <jasper verbose="0"
* package="my.package"
* uriroot="${webapps.dir}/${webapp.name}"
- * webXmlFragment="${build.dir}/generated_web.xml"
+ * webXmlInclude="${build.dir}/generated_web.xml"
* outputDir="${webapp.dir}/${webapp.name}/WEB-INF/src/my/package" />
* </pre>
*/
@@ -1346,7 +1346,7 @@ public class JspC extends Task implements Options {
}
/*
- * Assumes valid xml
+ * Assumes valid xml with no attribute values containing a '>' character.
*/
private String getElement(Reader reader) throws IOException {
StringBuilder result = new StringBuilder();
diff --git a/java/org/apache/jasper/Options.java b/java/org/apache/jasper/Options.java
index 7c8b4995fc..fe4f8c2a9b 100644
--- a/java/org/apache/jasper/Options.java
+++ b/java/org/apache/jasper/Options.java
@@ -299,7 +299,7 @@ public interface Options {
/**
* Returns whether tag pooling is allowed on JSP pages that use the extends directive.
*
- * @return {@code true} if tag pooling is disabled with page that uses extends.
+ * @return {@code true} if tag pooling is allowed on pages that use extends.
*/
default boolean getPoolTagsWithExtends() {
return false;
diff --git a/java/org/apache/jasper/compiler/AntCompiler.java b/java/org/apache/jasper/compiler/AntCompiler.java
index 342289b661..5c2dce7b40 100644
--- a/java/org/apache/jasper/compiler/AntCompiler.java
+++ b/java/org/apache/jasper/compiler/AntCompiler.java
@@ -36,7 +36,7 @@ import org.apache.tools.ant.types.Path;
import org.apache.tools.ant.types.PatternSet;
/**
- * Main JSP compiler class. This class uses Ant for compiling.
+ * JSP compiler class. This class uses Ant for compiling.
*/
public class AntCompiler extends Compiler {
@@ -305,7 +305,7 @@ public class AntCompiler extends Compiler {
/**
- * Construct the handler to capture the output of the given steam.
+ * Construct the handler to capture the output of the given stream.
*
* @param wrapped The wrapped stream
*/
diff --git a/java/org/apache/jasper/compiler/Compiler.java b/java/org/apache/jasper/compiler/Compiler.java
index ad2b1c2ca6..b424ab2634 100644
--- a/java/org/apache/jasper/compiler/Compiler.java
+++ b/java/org/apache/jasper/compiler/Compiler.java
@@ -41,7 +41,7 @@ import org.apache.tomcat.util.descriptor.tld.TldResourcePath;
import org.apache.tomcat.util.scan.JarFactory;
/**
- * Main JSP compiler class. This class uses Ant for compiling.
+ * Main JSP compiler class. Subclasses provide the actual compilation of the generated servlet source.
*/
public abstract class Compiler {
@@ -134,7 +134,8 @@ public abstract class Compiler {
/**
- * Compile the jsp file into equivalent servlet in .java file
+ * Compile the jsp file into equivalent servlet in .java file. The translation unit is parsed and validated, page
+ * info is collected, referenced tag files are processed and the JSR 045 source maps are generated.
*
* @return A map of class names to JSR 045 source maps
*
diff --git a/java/org/apache/jasper/compiler/ELNode.java b/java/org/apache/jasper/compiler/ELNode.java
index a50f774b79..0d11aa2c2c 100644
--- a/java/org/apache/jasper/compiler/ELNode.java
+++ b/java/org/apache/jasper/compiler/ELNode.java
@@ -26,7 +26,7 @@ import org.apache.jasper.JasperException;
/**
* This class defines internal representation for an EL Expression. It currently only defines functions. It can be
- * expanded to define all the components of an EL expression, if need to.
+ * expanded to define all the components of an EL expression, if needed to.
*/
public abstract class ELNode {
diff --git a/java/org/apache/jasper/compiler/ELParser.java b/java/org/apache/jasper/compiler/ELParser.java
index 7673d95606..3571a8fdd5 100644
--- a/java/org/apache/jasper/compiler/ELParser.java
+++ b/java/org/apache/jasper/compiler/ELParser.java
@@ -254,7 +254,8 @@ public class ELParser {
/**
- * Escape '\\', '\'' and '\"', inverting the unescaping performed in {@link #skipUntilEL()}.
+ * Escape '\\' in the input, and also the quote character when the input is a quoted string literal, inverting the
+ * unescaping performed in {@link #skipUntilEL()}.
*
* @param input Non-EL input to be escaped
*
diff --git a/java/org/apache/jasper/compiler/EncodingDetector.java b/java/org/apache/jasper/compiler/EncodingDetector.java
index d65d1a4c68..d5b4f6deb2 100644
--- a/java/org/apache/jasper/compiler/EncodingDetector.java
+++ b/java/org/apache/jasper/compiler/EncodingDetector.java
@@ -25,9 +25,6 @@ import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;
/*
- * The BoM detection is derived from:
- * https://svn.us.apache.org/viewvc/tomcat/trunk/java/org/apache/jasper/xmlparser/XMLEncodingDetector.java?annotate=1742248
- *
* The prolog is always at least as specific as the BOM therefore any encoding
* specified in the prolog should take priority over the BOM.
*/
diff --git a/java/org/apache/jasper/compiler/ErrorHandler.java b/java/org/apache/jasper/compiler/ErrorHandler.java
index 1d63abdd34..fb6c77dd4e 100644
--- a/java/org/apache/jasper/compiler/ErrorHandler.java
+++ b/java/org/apache/jasper/compiler/ErrorHandler.java
@@ -19,9 +19,8 @@ package org.apache.jasper.compiler;
import org.apache.jasper.JasperException;
/**
- * Interface for handling JSP parse and javac compilation errors. An implementation of this interface may be registered
- * with the ErrorDispatcher by setting the XXX initialization parameter in the JSP page compiler and execution servlet
- * in Catalina's web.xml file to the implementation's fully qualified class name.
+ * Interface for handling JSP parse and javac compilation errors. The {@link ErrorDispatcher} always uses
+ * {@link DefaultErrorHandler}.
*/
public interface ErrorHandler {
diff --git a/java/org/apache/jasper/compiler/JDTCompiler.java b/java/org/apache/jasper/compiler/JDTCompiler.java
index be7ed13959..c88cdb6809 100644
--- a/java/org/apache/jasper/compiler/JDTCompiler.java
+++ b/java/org/apache/jasper/compiler/JDTCompiler.java
@@ -56,7 +56,7 @@ import org.eclipse.jdt.internal.compiler.lookup.ModuleBinding;
import org.eclipse.jdt.internal.compiler.problem.DefaultProblemFactory;
/**
- * JDT class compiler. This compiler will load source dependencies from the context classloader, reducing dramatically
+ * JDT class compiler. This compiler will load source dependencies from the JSP classloader, reducing dramatically
* disk access during the compilation process. Based on code from Cocoon2.
*/
public class JDTCompiler extends org.apache.jasper.compiler.Compiler {
diff --git a/java/org/apache/jasper/compiler/JspReader.java b/java/org/apache/jasper/compiler/JspReader.java
index 2dff615496..cce323caf6 100644
--- a/java/org/apache/jasper/compiler/JspReader.java
+++ b/java/org/apache/jasper/compiler/JspReader.java
@@ -60,7 +60,7 @@ class JspReader {
* @param ctxt The compilation context
* @param fname The file name
* @param encoding The file encoding
- * @param jar ?
+ * @param jar The Jar containing the JSP file, or {@code null} if the JSP file is not in a Jar
* @param err The error dispatcher
*
* @throws JasperException If a Jasper-internal error occurs
diff --git a/java/org/apache/jasper/compiler/JspUtil.java b/java/org/apache/jasper/compiler/JspUtil.java
index 48b632ed3e..4d29cfd483 100644
--- a/java/org/apache/jasper/compiler/JspUtil.java
+++ b/java/org/apache/jasper/compiler/JspUtil.java
@@ -902,7 +902,7 @@ public class JspUtil {
*
* @param key The name
*
- * @return <code>true</code> if the name is a java identifier
+ * @return <code>true</code> if the name is a java keyword
*/
public static boolean isJavaKeyword(String key) {
int i = 0;
diff --git a/java/org/apache/jasper/compiler/Node.java b/java/org/apache/jasper/compiler/Node.java
index 030e35665f..c9a825babb 100644
--- a/java/org/apache/jasper/compiler/Node.java
+++ b/java/org/apache/jasper/compiler/Node.java
@@ -519,7 +519,7 @@ public abstract class Node implements TagConstants {
private boolean isEncodingSpecifiedInProlog;
/*
- * Indicates whether an encoding has been explicitly specified in the page's dom.
+ * Indicates whether a byte order mark (BOM) is present in the JSP source.
*/
private boolean isBomPresent;
diff --git a/java/org/apache/jasper/compiler/Parser.java b/java/org/apache/jasper/compiler/Parser.java
index 9f97ec62f9..d7f780029e 100644
--- a/java/org/apache/jasper/compiler/Parser.java
+++ b/java/org/apache/jasper/compiler/Parser.java
@@ -179,7 +179,7 @@ class Parser implements TagConstants {
* Attribute ::= Name S? Eq S? ( '"<%=' RTAttributeValueDouble | '"' * AttributeValueDouble | "'<%="
* RTAttributeValueSingle | "'" AttributeValueSingle }
* <p>
- * Note: JSP and XML spec does not allow while spaces around Eq. It is added to be backward compatible with Tomcat,
+ * Note: JSP and XML spec does not allow white spaces around Eq. It is added to be backward compatible with Tomcat,
* and with other xml parsers.
*/
private boolean parseAttribute(AttributesImpl attrs) throws JasperException {
diff --git a/java/org/apache/jasper/compiler/SmapUtil.java b/java/org/apache/jasper/compiler/SmapUtil.java
index d58668ab2c..fe3f2dc945 100644
--- a/java/org/apache/jasper/compiler/SmapUtil.java
+++ b/java/org/apache/jasper/compiler/SmapUtil.java
@@ -680,7 +680,9 @@ public class SmapUtil {
* attribute from the class file or an external .smap resource.
* @param className the fully qualified class name
* @param cl the class loader to use for loading the resource
- * @return the parsed SmapStratum, or {@code null} if no or invalid SMAP data is found
+ * @return the parsed SmapStratum, or {@code null} if no SMAP data is found
+ * @throws NumberFormatException If the SMAP data is found but is malformed
+ * @throws ArrayIndexOutOfBoundsException If the SMAP data is found but is malformed
*/
public static SmapStratum loadSmap(String className, ClassLoader cl) {
// Extract SMAP from class file. First line "SMAP" is not included
diff --git a/java/org/apache/jasper/compiler/TagFileProcessor.java b/java/org/apache/jasper/compiler/TagFileProcessor.java
index d2cf7e8aa5..3b445a71e3 100644
--- a/java/org/apache/jasper/compiler/TagFileProcessor.java
+++ b/java/org/apache/jasper/compiler/TagFileProcessor.java
@@ -323,7 +323,6 @@ public class TagFileProcessor {
public TagInfo getTagInfo(String packageName) throws JasperException {
if (name == null) {
- // XXX Get it from tag file name
}
if (bodyContent == null) {
@@ -629,7 +628,7 @@ public class TagFileProcessor {
* nodes.
*
* @param compiler Compiler to use to compile tag files
- * @param page The page from to scan for tag files to compile
+ * @param page The page from which to scan for tag files to compile
*
* @throws JasperException If an error occurs during the scan or compilation
*/
@@ -640,7 +639,7 @@ public class TagFileProcessor {
}
/**
- * Removed the java and class files for the tag prototype generated from the current compilation.
+ * Removes the java and class files for the tag prototype generated from the current compilation.
*
* @param classFileName If non-null, remove only the class file with this name.
*/
diff --git a/java/org/apache/jasper/compiler/TextOptimizer.java b/java/org/apache/jasper/compiler/TextOptimizer.java
index 389ffdbf2a..230672eb5e 100644
--- a/java/org/apache/jasper/compiler/TextOptimizer.java
+++ b/java/org/apache/jasper/compiler/TextOptimizer.java
@@ -26,7 +26,7 @@ import org.apache.jasper.TrimSpacesOption;
public class TextOptimizer {
/**
- * Constructs a new TextOptimizer. This utility class should not be instantiated.
+ * Constructs a new TextOptimizer.
*/
public TextOptimizer() {
}
diff --git a/java/org/apache/jasper/compiler/TldCache.java b/java/org/apache/jasper/compiler/TldCache.java
index 181fc73d62..593e767a04 100644
--- a/java/org/apache/jasper/compiler/TldCache.java
+++ b/java/org/apache/jasper/compiler/TldCache.java
@@ -35,7 +35,7 @@ import org.xml.sax.SAXException;
/**
* This class caches parsed instances of TLD files to remove the need for the same TLD to be parsed for each JSP that
- * references it. It does not protect against multiple threads processing the same new TLD, but it does ensure that each
+ * references it. It does not protect against multiple threads processing the same new TLD, but it does ensure that
* all threads will use the same TLD object after parsing.
*/
public class TldCache {
diff --git a/java/org/apache/jasper/compiler/Validator.java b/java/org/apache/jasper/compiler/Validator.java
index 0c5fa434c5..9936777009 100644
--- a/java/org/apache/jasper/compiler/Validator.java
+++ b/java/org/apache/jasper/compiler/Validator.java
@@ -329,7 +329,7 @@ class Validator {
/*
* Compares page encodings specified in various places, and throws exception in case of page encoding mismatch.
*
- * @param thePageDirEnc The value of the pageEncoding attribute of the page directive @param pageDir The page
+ * @param thePageDirEnc The value of the pageEncoding attribute of the tag directive @param pageDir The tag
* directive node
*
* @throws JasperException in case of page encoding mismatch
diff --git a/java/org/apache/jasper/compiler/tagplugin/TagPlugin.java b/java/org/apache/jasper/compiler/tagplugin/TagPlugin.java
index e1711c1d5c..306ae9ecc9 100644
--- a/java/org/apache/jasper/compiler/tagplugin/TagPlugin.java
+++ b/java/org/apache/jasper/compiler/tagplugin/TagPlugin.java
@@ -20,7 +20,8 @@ package org.apache.jasper.compiler.tagplugin;
* This interface is to be implemented by the plugin author, to supply an alternate implementation of the tag handlers.
* It can be used to specify the Java codes to be generated when a tag is invoked.
* <p>
- * An implementation of this interface must be registered in a file named "tagPlugins.xml" under WEB-INF.
+ * An implementation of this interface must be registered in a file named "tagPlugins.xml" under WEB-INF, or in a file
+ * named "META-INF/org.apache.jasper/tagPlugins.xml" in a JAR on the web application class loader.
*/
public interface TagPlugin {
diff --git a/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java b/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java
index eff4786765..4690543575 100644
--- a/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java
+++ b/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java
@@ -111,8 +111,8 @@ public interface TagPluginContext {
* obtained is limited to getPluginAttribute and setPluginAttribute, and queries (e.g. isScriptless()). There should
* be no calls to generate*().
*
- * @return The pluginContext for the parent node. null if the parent is not a custom tag, or if the pluginContext is
- * not available (because useTagPlugin is false, e.g).
+ * @return The pluginContext for the parent node. null if the parent is not a custom tag, or if the parent custom
+ * tag has no plugin context.
*/
TagPluginContext getParentContext();
diff --git a/java/org/apache/jasper/el/JasperELResolver.java b/java/org/apache/jasper/el/JasperELResolver.java
index 1bc1cc3622..5dd5bb35d2 100644
--- a/java/org/apache/jasper/el/JasperELResolver.java
+++ b/java/org/apache/jasper/el/JasperELResolver.java
@@ -46,7 +46,8 @@ import org.apache.jasper.runtime.JspRuntimeLibrary;
*/
public class JasperELResolver extends CompositeELResolver {
- // Keep aligned with class under test
+ // The number of resolvers to pre-allocate in the resolvers array
+ // Note: Keep aligned with test class
private static final int STANDARD_RESOLVERS_COUNT = 11;
private final AtomicInteger resolversSize = new AtomicInteger(0);
@@ -120,7 +121,7 @@ public class JasperELResolver extends CompositeELResolver {
}
}
// skip stream, static and collection-based resolvers (map,
- // resource, list, array) and bean
+ // resource, list, array) and record
start = index + 7;
if (JspRuntimeLibrary.GRAAL) {
start++;
@@ -164,7 +165,7 @@ public class JasperELResolver extends CompositeELResolver {
// skip collection (map, resource, list, and array) resolvers
index += 4;
- // call bean and the rest of resolvers
+ // call record and the rest of resolvers
int size = resolversSize.get();
for (int i = index; i < size; i++) {
result = resolvers[i].invoke(context, base, targetMethod, paramTypes, params);
diff --git a/java/org/apache/jasper/optimizations/StringInterpreterEnum.java b/java/org/apache/jasper/optimizations/StringInterpreterEnum.java
index c57fb3827e..ff52b6b1ac 100644
--- a/java/org/apache/jasper/optimizations/StringInterpreterEnum.java
+++ b/java/org/apache/jasper/optimizations/StringInterpreterEnum.java
@@ -22,7 +22,8 @@ import org.apache.juli.logging.Log;
import org.apache.juli.logging.LogFactory;
/**
- * Provides an optimised conversion of string values to Enums. It bypasses the check for registered PropertyEditor.
+ * Provides an optimised conversion of string values to Enums. It bypasses the PropertyEditorManager lookup for a
+ * registered PropertyEditor.
*/
public class StringInterpreterEnum extends DefaultStringInterpreter {
diff --git a/java/org/apache/jasper/runtime/JspRuntimeLibrary.java b/java/org/apache/jasper/runtime/JspRuntimeLibrary.java
index 278d7781fc..a42893dff8 100644
--- a/java/org/apache/jasper/runtime/JspRuntimeLibrary.java
+++ b/java/org/apache/jasper/runtime/JspRuntimeLibrary.java
@@ -220,7 +220,7 @@ public class JspRuntimeLibrary {
*
* @param s The string to coerce
* @param target The target class
- * @return the coerced value
+ * @return the coerced value, or {@code null} if the target type is not supported
*/
public static Object coerce(String s, Class<?> target) {
@@ -420,7 +420,6 @@ public class JspRuntimeLibrary {
}
Class<?> t = type.getComponentType();
String[] values = request.getParameterValues(param);
- // XXX Please check.
if (values == null) {
return;
}
@@ -684,7 +683,8 @@ public class JspRuntimeLibrary {
}
/**
- * Escape special shell characters.
+ * Escape special shell characters by prefixing them with a backslash. Despite the method name, this does not
+ * perform any URL or query string encoding.
*
* @param unescString The string to shell-escape
*
diff --git a/java/org/apache/jasper/runtime/JspWriterImpl.java b/java/org/apache/jasper/runtime/JspWriterImpl.java
index 498d919631..01357d01f3 100644
--- a/java/org/apache/jasper/runtime/JspWriterImpl.java
+++ b/java/org/apache/jasper/runtime/JspWriterImpl.java
@@ -89,8 +89,7 @@ public class JspWriterImpl extends JspWriter {
}
/**
- * Flush the output buffer to the underlying character stream, without flushing the stream itself. This method is
- * non-private only so that it may be invoked by PrintStream.
+ * Flush the output buffer to the underlying character stream, without flushing the stream itself.
*
* @throws IOException Error writing buffered data
*/
@@ -203,8 +202,7 @@ public class JspWriterImpl extends JspWriter {
}
/**
- * Our own little min method, to avoid loading java.lang.Math if we've run out of file descriptors, and we're trying
- * to print a stack trace.
+ * Returns the smaller of the two given values.
*/
private static int min(int a, int b) {
return Math.min(a, b);
diff --git a/java/org/apache/jasper/runtime/PageContextImpl.java b/java/org/apache/jasper/runtime/PageContextImpl.java
index 930de9f316..b58634d427 100644
--- a/java/org/apache/jasper/runtime/PageContextImpl.java
+++ b/java/org/apache/jasper/runtime/PageContextImpl.java
@@ -52,7 +52,7 @@ import org.apache.jasper.el.ELContextImpl;
import org.apache.jasper.runtime.JspContextWrapper.ELContextWrapper;
/**
- * Implementation of the PageContext class from the JSP spec. Also doubles as a VariableResolver for the EL.
+ * Implementation of the PageContext class from the JSP spec.
*/
public class PageContextImpl extends PageContext {
diff --git a/java/org/apache/jasper/runtime/TagHandlerPool.java b/java/org/apache/jasper/runtime/TagHandlerPool.java
index dcb6067bff..8ae0a13f64 100644
--- a/java/org/apache/jasper/runtime/TagHandlerPool.java
+++ b/java/org/apache/jasper/runtime/TagHandlerPool.java
@@ -67,7 +67,7 @@ public class TagHandlerPool {
protected boolean useInstanceManagerForTags;
/**
- * Creates or retrieves a TagHandlerPool for the given servlet configuration.
+ * Creates a TagHandlerPool for the given servlet configuration.
*
* @param config the servlet configuration
* @return the tag handler pool instance
diff --git a/java/org/apache/jasper/servlet/JasperLoader.java b/java/org/apache/jasper/servlet/JasperLoader.java
index 39933d43b3..9b3c1206e8 100644
--- a/java/org/apache/jasper/servlet/JasperLoader.java
+++ b/java/org/apache/jasper/servlet/JasperLoader.java
@@ -55,18 +55,17 @@ public class JasperLoader extends URLClassLoader {
}
/**
- * Load the class with the specified name, searching using the following algorithm until it finds and returns the
- * class. If the class cannot be found, returns <code>ClassNotFoundException</code>.
+ * Load the class with the specified name, using the following algorithm until it finds and returns the class. If
+ * the class cannot be found, a <code>ClassNotFoundException</code> is thrown.
* <ul>
* <li>Call <code>findLoadedClass(String)</code> to check if the class has already been loaded. If it has, the same
* <code>Class</code> object is returned.</li>
- * <li>If the <code>delegate</code> property is set to <code>true</code>, call the <code>loadClass()</code> method
- * of the parent class loader, if any.</li>
- * <li>Call <code>findClass()</code> to find this class in our locally defined repositories.</li>
- * <li>Call the <code>loadClass()</code> method of our parent class loader, if any.</li>
+ * <li>If the class is not in the JSP package, call the <code>loadClass()</code> method of the parent class
+ * loader.</li>
+ * <li>Otherwise, call <code>findClass()</code> to find this class in our locally defined repositories.</li>
* </ul>
- * If the class was found using the above steps, and the <code>resolve</code> flag is <code>true</code>, this method
- * will then call <code>resolveClass(Class)</code> on the resulting Class object.
+ * If the class was found by one of the first two steps, and the <code>resolve</code> flag is <code>true</code>, this
+ * method will then call <code>resolveClass(Class)</code> on the resulting Class object.
*
* @param name Name of the class to be loaded
* @param resolve If <code>true</code> then resolve the class
@@ -102,7 +101,8 @@ public class JasperLoader extends URLClassLoader {
/**
- * Delegate to parent
+ * Delegate to the parent class loader, falling back to the local repositories if the parent returns
+ * <code>null</code>.
*
* @see java.lang.ClassLoader#getResourceAsStream(String)
*/
diff --git a/java/org/apache/jasper/servlet/JspServletWrapper.java b/java/org/apache/jasper/servlet/JspServletWrapper.java
index be907e3652..ee7b9bebb1 100644
--- a/java/org/apache/jasper/servlet/JspServletWrapper.java
+++ b/java/org/apache/jasper/servlet/JspServletWrapper.java
@@ -49,9 +49,8 @@ import org.apache.tomcat.InstanceManager;
import org.apache.tomcat.Jar;
/**
- * The Jasper JSP engine. The servlet container is responsible for providing a URLClassLoader for the web application
- * context Jasper is being used in. Jasper will try to get the Tomcat ServletContext attribute for its ServletContext
- * class loader, if that fails, it uses the parent class loader. In either case, it must be a URLClassLoader.
+ * Holds the per-JSP (or tag file) state for the Jasper JSP engine: manages compilation on first use, reloading, and
+ * participation in the JSP unload queue.
*/
public class JspServletWrapper {
diff --git a/java/org/apache/jasper/tagplugins/jstl/Util.java b/java/org/apache/jasper/tagplugins/jstl/Util.java
index 47cdd1629a..9c6faa2e77 100644
--- a/java/org/apache/jasper/tagplugins/jstl/Util.java
+++ b/java/org/apache/jasper/tagplugins/jstl/Util.java
@@ -43,7 +43,7 @@ import org.apache.jasper.compiler.Localizer;
public class Util {
/**
- * Constructs a new Util instance.
+ * Constructs a new Util instance. This class consists only of static methods and instances hold no state.
*/
public Util() {
}
@@ -174,7 +174,7 @@ public class Util {
public static String stripSession(String url) {
StringBuilder u = new StringBuilder(url);
int sessionStart;
- while ((sessionStart = u.toString().indexOf(";" + "jsessionid" /* FIXME */ + "=")) != -1) {
+ while ((sessionStart = u.toString().indexOf(";" + "jsessionid" + "=")) != -1) {
int sessionEnd = u.toString().indexOf(';', sessionStart + 1);
if (sessionEnd == -1) {
sessionEnd = u.toString().indexOf('?', sessionStart + 1);
@@ -190,7 +190,7 @@ public class Util {
/**
* Performs the following substring replacements (to facilitate output to XML/HTML pages):
* <ul>
- * <li>{@code &} -> {@code &}</li>
+ * <li>{@code &} -> {@code &}</li>
* <li>{@code <} -> {@code <}</li>
* <li>{@code >} -> {@code >}</li>
* <li>{@code "} -> {@code "}</li>
@@ -215,7 +215,7 @@ public class Util {
*
* @return The escaped string, or {@code null} if no escaping was necessary
*/
- @SuppressWarnings("null") // escapedBuffer cannot be null
+ @SuppressWarnings("null") // escapedBuffer is non-null once a special character has been found
public static String escapeXml(char[] arrayBuffer, int length) {
int start = 0;
StringBuilder escapedBuffer = null;
@@ -259,7 +259,8 @@ public class Util {
*
* @return the absolute URL
*
- * @throws JspException If the URL doesn't start with '/'
+ * @throws JspException If the context is non-{@code null} and either the context or the URL doesn't start with
+ * '/'
*/
public static String resolveUrl(String url, String context, PageContext pageContext) throws JspException {
// don't touch absolute URLs
diff --git a/java/org/apache/jasper/tagplugins/jstl/core/ForEach.java b/java/org/apache/jasper/tagplugins/jstl/core/ForEach.java
index c2557693f9..66b8ff6304 100644
--- a/java/org/apache/jasper/tagplugins/jstl/core/ForEach.java
+++ b/java/org/apache/jasper/tagplugins/jstl/core/ForEach.java
@@ -68,8 +68,7 @@ public final class ForEach implements TagPlugin {
ctxt.generateJavaSource("; " + index + "++) {");
}
- // If var is specified and the body contains an EL, then sync
- // the var attribute
+ // If var is specified, sync the var attribute
if (hasVar /* && ctxt.hasEL() */) {
ctxt.generateJavaSource("_jspx_page_context.setAttribute(");
ctxt.generateAttribute("var");
@@ -80,7 +79,7 @@ public final class ForEach implements TagPlugin {
}
/**
- * Generate codes for Collections The pseudocode is:
+ * Generate codes for Collections.
*/
private void doCollection(TagPluginContext ctxt) {
diff --git a/java/org/apache/jasper/tagplugins/jstl/core/Otherwise.java b/java/org/apache/jasper/tagplugins/jstl/core/Otherwise.java
index 6920548a79..0e1217de4c 100644
--- a/java/org/apache/jasper/tagplugins/jstl/core/Otherwise.java
+++ b/java/org/apache/jasper/tagplugins/jstl/core/Otherwise.java
@@ -33,7 +33,7 @@ public final class Otherwise implements TagPlugin {
@Override
public void doTag(TagPluginContext ctxt) {
- // See When.java for the reason whey "}" is need at the beginning and
+ // See When.java for the reason why "}" is needed at the beginning and
// not at the end.
ctxt.generateJavaSource("} else {");
ctxt.generateBody();
diff --git a/java/org/apache/jasper/tagplugins/jstl/core/Out.java b/java/org/apache/jasper/tagplugins/jstl/core/Out.java
index 5e9aab8939..12cd8471b4 100644
--- a/java/org/apache/jasper/tagplugins/jstl/core/Out.java
+++ b/java/org/apache/jasper/tagplugins/jstl/core/Out.java
@@ -40,12 +40,12 @@ public final class Out implements TagPlugin {
@Override
public void doTag(TagPluginContext ctxt) {
- // these two data member are to indicate
+ // these two local variables are to indicate
// whether the corresponding attribute is specified
boolean hasDefault = ctxt.isAttributeSpecified("default");
boolean hasEscapeXml = ctxt.isAttributeSpecified("escapeXml");
- // strValName, strEscapeXmlName & strDefName are two variables' name
+ // strValName, strEscapeXmlName & strDefName are three variables' names
// standing for value, escapeXml and default attribute
String strObjectName = ctxt.getTemporaryVariableName();
String strValName = ctxt.getTemporaryVariableName();
@@ -53,7 +53,7 @@ public final class Out implements TagPlugin {
String strEscapeXmlName = ctxt.getTemporaryVariableName();
String strSkipBodyName = ctxt.getTemporaryVariableName();
- // according to the tag file, the value attribute is mandatory.
+ // the value attribute is not mandatory; the tag body is a fallback.
ctxt.generateImport("java.io.Reader");
ctxt.generateJavaSource("Object " + strObjectName + "=");
ctxt.generateAttribute("value");
diff --git a/java/org/apache/jasper/tagplugins/jstl/core/Url.java b/java/org/apache/jasper/tagplugins/jstl/core/Url.java
index 8538208df0..8772218a75 100644
--- a/java/org/apache/jasper/tagplugins/jstl/core/Url.java
+++ b/java/org/apache/jasper/tagplugins/jstl/core/Url.java
@@ -88,7 +88,7 @@ public class Url implements TagPlugin {
ctxt.generateJavaSource(" " + resultName + " = " + responseName + ".encodeURL(" + resultName + ");");
ctxt.generateJavaSource("}");
- // if "var" is specified, the url string store in the attribute var defines
+ // if "var" is specified, the url string is stored in the attribute var
if (hasVar) {
String strVar = ctxt.getConstantAttribute("var");
ctxt.generateJavaSource(
diff --git a/java/org/apache/jasper/util/FastRemovalDequeue.java b/java/org/apache/jasper/util/FastRemovalDequeue.java
index a0ff79a305..8fdce038b1 100644
--- a/java/org/apache/jasper/util/FastRemovalDequeue.java
+++ b/java/org/apache/jasper/util/FastRemovalDequeue.java
@@ -67,8 +67,7 @@ public class FastRemovalDequeue<T> {
}
/**
- * Retrieve the size of the list. This method also needs to be externally synchronized to ensure correct publication
- * of changes.
+ * Retrieve the size of the list.
*
* @return the size of the list.
*/
diff --git a/java/org/apache/juli/FileHandler.java b/java/org/apache/juli/FileHandler.java
index 29562dccaa..3ae058391d 100644
--- a/java/org/apache/juli/FileHandler.java
+++ b/java/org/apache/juli/FileHandler.java
@@ -60,8 +60,8 @@ import java.util.regex.Pattern;
* will not be rotated and the filename will be <code>{prefix}{suffix}</code>. Default value: <code>true</code></li>
* <li><code>prefix</code> - The leading part of the log file name. Default value: <code>juli.</code></li>
* <li><code>suffix</code> - The trailing part of the log file name. Default value: <code>.log</code></li>
- * <li><code>bufferSize</code> - Configures buffering. The value of <code>0</code> uses system default buffering
- * (typically an 8K buffer will be used). A value of <code><0</code> forces a writer flush upon each log write. A
+ * <li><code>bufferSize</code> - Configures buffering. The value of <code>0</code> uses no application-level buffering.
+ * A value of <code><0</code> forces a writer flush upon each log write. A
* value <code>>0</code> uses a BufferedOutputStream with the defined value but note that the system default
* buffering will also be applied. Default value: <code>-1</code></li>
* <li><code>encoding</code> - Character set used by the log file. Default value: empty string, which means to use the
diff --git a/java/org/apache/juli/JsonFormatter.java b/java/org/apache/juli/JsonFormatter.java
index d75c3c4c34..3ed301c1e4 100644
--- a/java/org/apache/juli/JsonFormatter.java
+++ b/java/org/apache/juli/JsonFormatter.java
@@ -27,7 +27,7 @@ import java.util.logging.LogRecord;
* <ul>
* <li>time: the log record timestamp, with the default format as {@code yyyy-MM-dd'T'HH:mm:ss.SSSX}</li>
* <li>level: the log level</li>
- * <li>thread: the current on which the log occurred</li>
+ * <li>thread: the name of the thread on which the log occurred</li>
* <li>class: the class from which the log originated</li>
* <li>method: the method from which the log originated</li>
* <li>message: the log message</li>
@@ -35,6 +35,9 @@ import java.util.logging.LogRecord;
* first, then one string per stack trace element prefixed by a whitespace, then moving on to the cause exception if
* any)</li>
* </ul>
+ * <p>
+ * Note that the values of the {@code level}, {@code thread}, {@code class} and {@code method} attributes are written
+ * to the JSON document without JSON escaping.
*/
public class JsonFormatter extends OneLineFormatter {
diff --git a/java/org/apache/juli/OneLineFormatter.java b/java/org/apache/juli/OneLineFormatter.java
index f0aff1ee08..04e3182314 100644
--- a/java/org/apache/juli/OneLineFormatter.java
+++ b/java/org/apache/juli/OneLineFormatter.java
@@ -111,7 +111,7 @@ public class OneLineFormatter extends Formatter {
/**
* Obtain the format currently being used for time stamps in log messages.
*
- * @return The current format in {@link java.text.SimpleDateFormat} syntax
+ * @return The current format, with each unquoted 'S' (millisecond) character replaced by the '#' placeholder
*/
public String getTimeFormat() {
return localDateCache.get().getTimeFormat();
diff --git a/java/org/apache/juli/logging/Log.java b/java/org/apache/juli/logging/Log.java
index 11de9d5937..800f4d722a 100644
--- a/java/org/apache/juli/logging/Log.java
+++ b/java/org/apache/juli/logging/Log.java
@@ -148,7 +148,7 @@ public interface Log {
/**
* <p>
- * Log an error with trace log level.
+ * Log a message and its cause with trace log level.
* </p>
*
* @param message log this message
@@ -169,7 +169,7 @@ public interface Log {
/**
* <p>
- * Log an error with debug log level.
+ * Log a message and its cause with debug log level.
* </p>
*
* @param message log this message
@@ -190,7 +190,7 @@ public interface Log {
/**
* <p>
- * Log an error with info log level.
+ * Log a message and its cause with info log level.
* </p>
*
* @param message log this message
@@ -211,7 +211,7 @@ public interface Log {
/**
* <p>
- * Log an error with warn log level.
+ * Log a message and its cause with warn log level.
* </p>
*
* @param message log this message
@@ -232,7 +232,7 @@ public interface Log {
/**
* <p>
- * Log an error with error log level.
+ * Log a message and its cause with error log level.
* </p>
*
* @param message log this message
@@ -253,7 +253,7 @@ public interface Log {
/**
* <p>
- * Log an error with fatal log level.
+ * Log a message and its cause with fatal log level.
* </p>
*
* @param message log this message
diff --git a/java/org/apache/juli/logging/LogFactory.java b/java/org/apache/juli/logging/LogFactory.java
index 1696c84ef8..4df17a1f0a 100644
--- a/java/org/apache/juli/logging/LogFactory.java
+++ b/java/org/apache/juli/logging/LogFactory.java
@@ -32,9 +32,7 @@ import aQute.bnd.annotation.spi.ServiceConsumer;
* particularly for those projects that embed Tomcat or some of Tomcat's components - is an alternative logging
* implementation is desired.
* <p>
- * Note that this implementation is not just a wrapper around JDK logging (like the original commons-logging impl). It
- * adds 2 features - a simpler configuration (which is in fact a subset of log4j.properties) and a formatter that is
- * less ugly.
+ * Note that this implementation is not just a wrapper around JDK logging (like the original commons-logging impl).
* <p>
* The removal of 'abstract' preserves binary backward compatibility. It is possible to preserve the abstract - and
* introduce another (hardcoded) factory - but I see no benefit.
@@ -145,22 +143,9 @@ public class LogFactory {
/**
* <p>
- * Construct (if necessary) and return a <code>LogFactory</code> instance, using the following ordered lookup
- * procedure to determine the name of the implementation class to be loaded.
- * </p>
- * <ul>
- * <li>The <code>org.apache.commons.logging.LogFactory</code> system property.</li>
- * <li>The JDK 1.3 Service Discovery mechanism</li>
- * <li>Use the properties file <code>commons-logging.properties</code> file, if found in the class path of this
- * class. The configuration file is in standard <code>java.util.Properties</code> format and contains the fully
- * qualified name of the implementation class with the key being the system property defined above.</li>
- * <li>Fall back to a default implementation class
- * (<code>org.apache.commons.logging.impl.LogFactoryImpl</code>).</li>
- * </ul>
- * <p>
- * <em>NOTE</em> - If the properties file method of identifying the <code>LogFactory</code> implementation class is
- * utilized, all of the properties defined in this file will be set as configuration attributes on the corresponding
- * <code>LogFactory</code> instance.
+ * Return the singleton <code>LogFactory</code> instance. The {@link Log} implementation is discovered once, using
+ * a {@link java.util.ServiceLoader} lookup for providers of the <code>Log</code> interface, falling back to
+ * {@link DirectJDKLog} if no suitable provider is found.
* </p>
*
* @return The singleton LogFactory instance
@@ -202,10 +187,11 @@ public class LogFactory {
/**
- * Release any internal references to previously created {@link LogFactory} instances that have been associated with
- * the specified class loader (if any), after calling the instance method <code>release()</code> on each of them.
+ * Reset the {@link java.util.logging.LogManager}, unless the standard <code>java.util.logging.LogManager</code>
+ * implementation is in use. The given class loader is not used: the JULI log manager associates its configuration
+ * with the current thread's context class loader.
*
- * @param classLoader ClassLoader for which to release the LogFactory
+ * @param classLoader ClassLoader for which to release the LogFactory. Not used by this implementation.
*/
public static void release(ClassLoader classLoader) {
// JULI's log manager looks at the current classLoader so there is no
diff --git a/java/org/apache/naming/ContextAccessController.java b/java/org/apache/naming/ContextAccessController.java
index 5b5ee9c7f2..244014d572 100644
--- a/java/org/apache/naming/ContextAccessController.java
+++ b/java/org/apache/naming/ContextAccessController.java
@@ -100,7 +100,7 @@ public class ContextAccessController {
/**
- * Set whether or not a Catalina context is writable.
+ * Mark a Catalina context as read-only.
*
* @param name Name of the Catalina context
*/
@@ -110,7 +110,7 @@ public class ContextAccessController {
/**
- * Is the context is writable?
+ * Is the context writable?
*
* @param name Name of the Catalina context
*
diff --git a/java/org/apache/naming/HandlerRef.java b/java/org/apache/naming/HandlerRef.java
index b058c1826b..edef46713f 100644
--- a/java/org/apache/naming/HandlerRef.java
+++ b/java/org/apache/naming/HandlerRef.java
@@ -48,25 +48,25 @@ public class HandlerRef extends AbstractRef {
/**
- * Handler Classname address type.
+ * Handler Classname local part address type.
*/
public static final String HANDLER_LOCALPART = "handlerlocalpart";
/**
- * Handler Classname address type.
+ * Handler Classname namespace address type.
*/
public static final String HANDLER_NAMESPACE = "handlernamespace";
/**
- * Handler Classname address type.
+ * Handler param name address type.
*/
public static final String HANDLER_PARAMNAME = "handlerparamname";
/**
- * Handler Classname address type.
+ * Handler param value address type.
*/
public static final String HANDLER_PARAMVALUE = "handlerparamvalue";
diff --git a/java/org/apache/naming/NamingContext.java b/java/org/apache/naming/NamingContext.java
index 4cdb6ed63b..740f02c5bc 100644
--- a/java/org/apache/naming/NamingContext.java
+++ b/java/org/apache/naming/NamingContext.java
@@ -657,7 +657,7 @@ public class NamingContext implements Context {
/**
- * Throws a naming exception is Context is not writable.
+ * Throws a naming exception if Context is not writable.
*
* @return <code>true</code> if the Context is writable
*
diff --git a/java/org/apache/naming/ResourceLinkRef.java b/java/org/apache/naming/ResourceLinkRef.java
index 8cf7470d22..a517d4a1bf 100644
--- a/java/org/apache/naming/ResourceLinkRef.java
+++ b/java/org/apache/naming/ResourceLinkRef.java
@@ -21,7 +21,7 @@ import java.io.Serial;
import javax.naming.StringRefAddr;
/**
- * Represents a reference address to a resource.
+ * Represents a reference address to a resource link.
*/
public class ResourceLinkRef extends AbstractRef {
@@ -36,7 +36,7 @@ public class ResourceLinkRef extends AbstractRef {
/**
- * Description address type.
+ * Global name address type.
*/
public static final String GLOBALNAME = "globalName";
diff --git a/java/org/apache/naming/ServiceRef.java b/java/org/apache/naming/ServiceRef.java
index caa3c39302..49a0533e6b 100644
--- a/java/org/apache/naming/ServiceRef.java
+++ b/java/org/apache/naming/ServiceRef.java
@@ -140,9 +140,11 @@ public class ServiceRef extends AbstractRef {
/**
- * Add and Get Handlers classes.
+ * Get and remove the first handler.
*
* @return the handler
+ *
+ * @throws NoSuchElementException if there are no handlers
*/
public HandlerRef getHandler() {
return handlers.removeFirst();
diff --git a/java/org/apache/naming/TransactionRef.java b/java/org/apache/naming/TransactionRef.java
index 8a5a8c7791..71eeec68b5 100644
--- a/java/org/apache/naming/TransactionRef.java
+++ b/java/org/apache/naming/TransactionRef.java
@@ -34,7 +34,7 @@ public class TransactionRef extends AbstractRef {
/**
- * Resource Reference.
+ * Transaction Reference.
*/
public TransactionRef() {
this(null, null);
@@ -42,7 +42,7 @@ public class TransactionRef extends AbstractRef {
/**
- * Resource Reference.
+ * Transaction Reference.
*
* @param factory The factory class
* @param factoryLocation The factory location
diff --git a/java/org/apache/naming/factory/DataSourceLinkFactory.java b/java/org/apache/naming/factory/DataSourceLinkFactory.java
index ac36cba598..301ca1bf29 100644
--- a/java/org/apache/naming/factory/DataSourceLinkFactory.java
+++ b/java/org/apache/naming/factory/DataSourceLinkFactory.java
@@ -56,6 +56,18 @@ public class DataSourceLinkFactory extends ResourceLinkFactory {
// ------------------------------------------------- ObjectFactory Methods
+ /**
+ * Create a new resource instance.
+ *
+ * @param obj The reference object describing the DataSource
+ * @param name the bound name
+ * @param nameCtx unused
+ * @param environment unused
+ *
+ * @return the object instance
+ *
+ * @throws NamingException if an error occurs creating the instance
+ */
@Override
public Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment)
throws NamingException {
diff --git a/java/org/apache/naming/factory/LookupFactory.java b/java/org/apache/naming/factory/LookupFactory.java
index 44877de4e9..90f5a7440e 100644
--- a/java/org/apache/naming/factory/LookupFactory.java
+++ b/java/org/apache/naming/factory/LookupFactory.java
@@ -51,7 +51,7 @@ public class LookupFactory implements ObjectFactory {
/**
* Create a new Resource env instance.
*
- * @param obj The reference object describing the DataSource
+ * @param obj The reference object describing the LookupRef
* @param name the bound name
* @param nameCtx unused
* @param environment unused
diff --git a/java/org/apache/naming/factory/MailSessionFactory.java b/java/org/apache/naming/factory/MailSessionFactory.java
index e554ec2ff9..945efafa43 100644
--- a/java/org/apache/naming/factory/MailSessionFactory.java
+++ b/java/org/apache/naming/factory/MailSessionFactory.java
@@ -67,6 +67,22 @@ public class MailSessionFactory implements ObjectFactory {
protected static final String factoryType = "jakarta.mail.Session";
+ /**
+ * Create a new resource instance.
+ * <p>
+ * The {@code password} attribute is only used when {@code mail.smtp.user} or {@code mail.user} is also
+ * configured; a password without a user is ignored.
+ * </p>
+ *
+ * @param refObj The reference object describing the Session
+ * @param name the bound name
+ * @param context unused
+ * @param env unused
+ *
+ * @return the object instance
+ *
+ * @throws Exception if an error occurs creating the instance
+ */
@Override
public Object getObjectInstance(Object refObj, Name name, Context context, Hashtable<?,?> env) throws Exception {
diff --git a/java/org/apache/naming/factory/OpenEjbFactory.java b/java/org/apache/naming/factory/OpenEjbFactory.java
index 44a187a6a3..f3ac0acffa 100644
--- a/java/org/apache/naming/factory/OpenEjbFactory.java
+++ b/java/org/apache/naming/factory/OpenEjbFactory.java
@@ -46,7 +46,7 @@ public class OpenEjbFactory implements ObjectFactory {
/**
* Create a new EJB instance using OpenEJB.
*
- * @param obj The reference object describing the DataSource
+ * @param obj The reference object describing the EJB
* @param name the bound name
* @param nameCtx unused
* @param environment unused
diff --git a/java/org/apache/naming/factory/ResourceLinkFactory.java b/java/org/apache/naming/factory/ResourceLinkFactory.java
index aa6d4d2d04..5c8f35c48a 100644
--- a/java/org/apache/naming/factory/ResourceLinkFactory.java
+++ b/java/org/apache/naming/factory/ResourceLinkFactory.java
@@ -58,7 +58,7 @@ public class ResourceLinkFactory implements ObjectFactory {
// --------------------------------------------------------- Public Methods
/**
- * Set the global context (note: can only be used once).
+ * Set the global context (the last value set is used).
*
* @param newGlobalContext new global context value
*/
@@ -77,8 +77,6 @@ public class ResourceLinkFactory implements ObjectFactory {
public static void registerGlobalResourceAccess(Context globalContext, String localName, String globalName) {
validateGlobalContext(globalContext);
ClassLoader cl = Thread.currentThread().getContextClassLoader();
- // Web application initialization is single threaded so this is
- // safe.
globalResourceRegistrations.computeIfAbsent(cl, k -> new ConcurrentHashMap<>()).put(localName, globalName);
}
@@ -142,7 +140,8 @@ public class ResourceLinkFactory implements ObjectFactory {
*
* @return the object instance
*
- * @throws NamingException if an error occur creating the instance
+ * @throws IllegalArgumentException if the type of the reference is missing or does not match the type of the
+ * global resource
*/
@Override
public Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment)
diff --git a/java/org/apache/naming/factory/SendMailFactory.java b/java/org/apache/naming/factory/SendMailFactory.java
index 1a8a1be8ca..dad3aecf92 100644
--- a/java/org/apache/naming/factory/SendMailFactory.java
+++ b/java/org/apache/naming/factory/SendMailFactory.java
@@ -115,7 +115,8 @@ public class SendMailFactory implements ObjectFactory {
message.setSubject("");
} catch (Throwable t) {
ExceptionUtils.handleThrowable(t);
- // Otherwise ignore
+ // Ignore. Failures to apply the mail.from address or the subject are swallowed; the resource is returned
+ // without them and no error is reported.
}
return new MimePartDataSource(message);
diff --git a/java/org/apache/naming/java/javaURLContextFactory.java b/java/org/apache/naming/java/javaURLContextFactory.java
index 96983d4bd9..a9ab4ed8bb 100644
--- a/java/org/apache/naming/java/javaURLContextFactory.java
+++ b/java/org/apache/naming/java/javaURLContextFactory.java
@@ -85,7 +85,7 @@ public class javaURLContextFactory implements ObjectFactory, InitialContextFacto
*
* @return a selector context if the thread or classloader are bound, and null otherwise
*
- * @throws NamingException not thrown by this implementationm
+ * @throws NamingException not thrown by this implementation
*/
@SuppressWarnings("unchecked")
@Override
@@ -105,7 +105,7 @@ public class javaURLContextFactory implements ObjectFactory, InitialContextFacto
*
* @return a selector context if the thread or classloader are bound, and a shared writable context otherwise
*
- * @throws NamingException not thrown by this implementationm
+ * @throws NamingException not thrown by this implementation
*/
@SuppressWarnings("unchecked")
@Override
diff --git a/java/org/apache/tomcat/InstanceManager.java b/java/org/apache/tomcat/InstanceManager.java
index 19e5296040..e9618236d6 100644
--- a/java/org/apache/tomcat/InstanceManager.java
+++ b/java/org/apache/tomcat/InstanceManager.java
@@ -37,7 +37,7 @@ public interface InstanceManager {
* an interface, an array class, a primitive type, or void
* @throws IllegalArgumentException if this method is invoked with illegal arguments
* @throws NoSuchMethodException if the nullary method cannot be found
- * @throws SecurityException if a security manager, s, is present
+ * @throws SecurityException if a security manager is present
*/
Object newInstance(Class<?> clazz) throws IllegalAccessException, InvocationTargetException, NamingException,
InstantiationException, IllegalArgumentException, NoSuchMethodException, SecurityException;
@@ -55,7 +55,7 @@ public interface InstanceManager {
* @throws ClassNotFoundException if the class cannot be found
* @throws IllegalArgumentException if this method is invoked with illegal arguments
* @throws NoSuchMethodException if the nullary method cannot be found
- * @throws SecurityException if a security manager, s, is present
+ * @throws SecurityException if a security manager is present
*/
Object newInstance(String className)
throws IllegalAccessException, InvocationTargetException, NamingException, InstantiationException,
@@ -75,7 +75,7 @@ public interface InstanceManager {
* @throws ClassNotFoundException if the class cannot be found
* @throws IllegalArgumentException if this method is invoked with illegal arguments
* @throws NoSuchMethodException if the nullary method cannot be found
- * @throws SecurityException if a security manager, s, is present
+ * @throws SecurityException if a security manager is present
*/
Object newInstance(String fqcn, ClassLoader classLoader)
throws IllegalAccessException, InvocationTargetException, NamingException, InstantiationException,
@@ -85,8 +85,6 @@ public interface InstanceManager {
* Perform dependency injection on the given object.
*
* @param o The object to inject dependencies into
- * @throws IllegalAccessException if the class or its nullary constructor is not accessible
- * @throws InvocationTargetException if the nullary constructor throws an exception
* @throws NamingException if a naming exception is encountered
*/
void newInstance(Object o) throws IllegalAccessException, InvocationTargetException, NamingException;
diff --git a/java/org/apache/tomcat/InstrumentableClassLoader.java b/java/org/apache/tomcat/InstrumentableClassLoader.java
index 4f798b1f93..d440748c4d 100644
--- a/java/org/apache/tomcat/InstrumentableClassLoader.java
+++ b/java/org/apache/tomcat/InstrumentableClassLoader.java
@@ -24,8 +24,7 @@ import java.lang.instrument.ClassFileTransformer;
* only {@link org.apache.catalina.loader.WebappClassLoaderBase} implements this interface. This allows web application
* frameworks or JPA providers bundled with a web application to instrument web application classes as necessary.
* <p>
- * You should always program against the methods of this interface (whether using reflection or otherwise). The methods
- * in {@code WebappClassLoaderBase} are protected by the default security manager if one is in use.
+ * You should always program against the methods of this interface (whether using reflection or otherwise).
*
* @since 8.0, 7.0.64
*/
diff --git a/java/org/apache/tomcat/Jar.java b/java/org/apache/tomcat/Jar.java
index 0afa18d1c2..c1351fa09f 100644
--- a/java/org/apache/tomcat/Jar.java
+++ b/java/org/apache/tomcat/Jar.java
@@ -53,8 +53,7 @@ public interface Jar extends AutoCloseable {
/**
* Obtain the last modified time for the JAR.
*
- * @return The time (in the same format as {@link System#currentTimeMillis()}) that the resource was last modified.
- * Returns -1 if the entry does not exist
+ * @return The time (in the same format as {@link System#currentTimeMillis()}) that the JAR was last modified.
*
* @throws IOException if an I/O error occurs while processing the JAR file
*/
@@ -128,8 +127,8 @@ public interface Jar extends AutoCloseable {
/**
* Obtain, in String form, the URL for an entry in this JAR. Note that for JARs nested in WAR files, the Tomcat
- * specific war:file:... form will not be used, rather the jar:jar:file:... form (that the JRE does not understand
- * will be used). Note that this means that any code using these URLs will need to understand the jar:jar:file:...
+ * specific war:file:... form will not be used, rather the jar:jar:file:... form (that the JRE does not understand)
+ * will be used. Note that this means that any code using these URLs will need to understand the jar:jar:file:...
* form and use the {@link org.apache.tomcat.util.scan.JarFactory} to ensure resources are accessed correctly.
*
* @param entry The entry to generate the URL for
diff --git a/java/org/apache/tomcat/SimpleInstanceManager.java b/java/org/apache/tomcat/SimpleInstanceManager.java
index b40356bbb6..90762ebf9d 100644
--- a/java/org/apache/tomcat/SimpleInstanceManager.java
+++ b/java/org/apache/tomcat/SimpleInstanceManager.java
@@ -21,7 +21,8 @@ import java.lang.reflect.InvocationTargetException;
import javax.naming.NamingException;
/**
- * SimpleInstanceManager implements the org.apache.tomcat.InstanceManager interface.
+ * SimpleInstanceManager implements the org.apache.tomcat.InstanceManager interface. Instances are created using their
+ * public no-argument constructor. No dependency injection is performed and no pre-destroy callbacks are invoked.
*/
public class SimpleInstanceManager implements InstanceManager {
@@ -74,6 +75,7 @@ public class SimpleInstanceManager implements InstanceManager {
*/
@Override
public void destroyInstance(Object o) throws IllegalAccessException, InvocationTargetException {
+ // NO-OP
}
private Object prepareInstance(Object o) {
diff --git a/java/org/apache/tomcat/buildutil/Txt2Html.java b/java/org/apache/tomcat/buildutil/Txt2Html.java
index d44335eae2..06d89f8243 100644
--- a/java/org/apache/tomcat/buildutil/Txt2Html.java
+++ b/java/org/apache/tomcat/buildutil/Txt2Html.java
@@ -55,7 +55,8 @@ public class Txt2Html extends Task {
private final List<FileSet> filesets = new ArrayList<>();
/**
- * The encoding of the source files (.java and .jsp). Once they use UTF-8, this will need to be updated.
+ * The encoding used to read the source files (.java and .jsp). All the files this task converts are
+ * ASCII only, so ISO-8859-1 is safe.
*/
private static final String SOURCE_ENCODING = "ISO-8859-1";
diff --git a/java/org/apache/tomcat/buildutil/translate/BackportEnglish.java b/java/org/apache/tomcat/buildutil/translate/BackportEnglish.java
index 4103961995..0bdfc1d11c 100644
--- a/java/org/apache/tomcat/buildutil/translate/BackportEnglish.java
+++ b/java/org/apache/tomcat/buildutil/translate/BackportEnglish.java
@@ -22,8 +22,9 @@ import java.util.Set;
/**
* Generates a set of English property files to back-port updates to a previous version. Where a key exists in the
- * source and target versions the value is copied from the source to the target, overwriting the value in the target.
- * The expectation is that the changes will be manually reviewed before committing them.
+ * source and target versions the value is copied from the source to the target, overwriting the value in the target,
+ * except for a small number of keys that are known to be different between versions. The expectation is that the
+ * changes will be manually reviewed before committing them.
*/
public class BackportEnglish extends BackportBase {
diff --git a/java/org/apache/tomcat/buildutil/translate/Constants.java b/java/org/apache/tomcat/buildutil/translate/Constants.java
index 6895b9c583..9cf2b9f801 100644
--- a/java/org/apache/tomcat/buildutil/translate/Constants.java
+++ b/java/org/apache/tomcat/buildutil/translate/Constants.java
@@ -31,12 +31,12 @@ public class Constants {
public static final String L10N_SUFFIX = ".properties";
/**
- * Directories to search for source files.
+ * Directories (relative to a source or target tree root) to search for LocalStrings files.
*/
public static final String[] SEARCH_DIRS = new String[] { "java", "webapps" };
/**
- * Directory for storing translation settings.
+ * Directory for storing the exported and imported combined LocalStrings translation files.
*/
public static final String STORAGE_DIR = ".settings/translations";
diff --git a/java/org/apache/tomcat/buildutil/translate/Utils.java b/java/org/apache/tomcat/buildutil/translate/Utils.java
index 97716b4c2c..fce8148bed 100644
--- a/java/org/apache/tomcat/buildutil/translate/Utils.java
+++ b/java/org/apache/tomcat/buildutil/translate/Utils.java
@@ -133,10 +133,7 @@ public class Utils {
* Common formatting to convert a String value for storage as a value in a property file. Values that contain
* line-breaks need the line-break in the value to be replaced with the correct representation of a line-break in a
* property file. Leading space needs to be escaped with a '\' and horizontal tabs need to be converted to "\t".
- *
- * Note that a single '\' needs to be escaped both in a Java string and in a property file so if a property value
- * needs to contain a single `\` (e.g. to escape white space at the start of a line) that will appear as "\\\\" in
- * the Java code.
+ * Backslashes are passed through unchanged.
*/
static String formatValueCommon(String in) {
String result = in.replace("\n", "\\n\\\n");
diff --git a/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionContext.java b/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionContext.java
index d5fb3853b9..3ba78b2455 100644
--- a/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionContext.java
+++ b/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionContext.java
@@ -159,7 +159,7 @@ public class TransactionContext {
}
/**
- * Gets the transaction complete flag to true.
+ * Gets the transaction complete flag.
*
* @return The transaction complete flag.
* @since 2.4.0
diff --git a/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionRegistry.java b/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionRegistry.java
index b857312be6..32331d8450 100644
--- a/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionRegistry.java
+++ b/java/org/apache/tomcat/dbcp/dbcp2/managed/TransactionRegistry.java
@@ -69,7 +69,7 @@ public class TransactionRegistry {
}
/**
- * Gets the active TransactionContext or null if not Transaction is active.
+ * Gets the active TransactionContext or null if no Transaction is active.
*
* @return The active TransactionContext or null if no Transaction is active.
* @throws SQLException
@@ -142,10 +142,10 @@ public class TransactionRegistry {
}
/**
- * Unregisters a destroyed connection from {@link TransactionRegistry}.
+ * Unregisters a destroyed connection.
*
* @param connection
- * A destroyed connection from {@link TransactionRegistry}.
+ * The destroyed connection.
*/
public synchronized void unregisterConnection(final Connection connection) {
xaResources.remove(getConnectionKey(connection));
diff --git a/java/org/apache/tomcat/dbcp/pool2/TrackedUse.java b/java/org/apache/tomcat/dbcp/pool2/TrackedUse.java
index 4c22ddff5d..e7a2b8ff72 100644
--- a/java/org/apache/tomcat/dbcp/pool2/TrackedUse.java
+++ b/java/org/apache/tomcat/dbcp/pool2/TrackedUse.java
@@ -19,7 +19,7 @@ package org.apache.tomcat.dbcp.pool2;
import java.time.Instant;
/**
- * Allows pooled objects to make information available about when and how they were used available to the object pool.
+ * Allows pooled objects to make information about when and how they were used available to the object pool.
* The object pool may, but is not required, to use this information to make more informed decisions when determining
* the state of a pooled object - for instance whether or not the object has been abandoned.
*
diff --git a/java/org/apache/tomcat/dbcp/pool2/impl/SoftReferenceObjectPool.java b/java/org/apache/tomcat/dbcp/pool2/impl/SoftReferenceObjectPool.java
index d2df8a6e05..b6c859e7f6 100644
--- a/java/org/apache/tomcat/dbcp/pool2/impl/SoftReferenceObjectPool.java
+++ b/java/org/apache/tomcat/dbcp/pool2/impl/SoftReferenceObjectPool.java
@@ -53,7 +53,7 @@ public class SoftReferenceObjectPool<T> extends BaseObjectPool<T> {
*/
private final ReferenceQueue<T> refQueue = new ReferenceQueue<>();
- /** Count of instances that have been checkout out to pool clients */
+ /** Count of instances that have been checked out to pool clients */
private int numActive; // @GuardedBy("this")
/** Total number of instances that have been destroyed */
@@ -125,7 +125,7 @@ public class SoftReferenceObjectPool<T> extends BaseObjectPool<T> {
final boolean shouldDestroy = !success;
if (success) {
idleReferences.add(ref);
- notifyAll(); // numActive has changed
+ notifyAll();
}
if (shouldDestroy) {
@@ -313,7 +313,7 @@ public class SoftReferenceObjectPool<T> extends BaseObjectPool<T> {
}
/**
- * Gets an approximation not less than the of the number of idle
+ * Gets an approximation not less than the number of idle
* instances in the pool.
*
* @return estimated number of idle instances in the pool
diff --git a/java/org/apache/tomcat/dbcp/pool2/impl/ThrowableCallStack.java b/java/org/apache/tomcat/dbcp/pool2/impl/ThrowableCallStack.java
index 616a035360..5146f2c3c1 100644
--- a/java/org/apache/tomcat/dbcp/pool2/impl/ThrowableCallStack.java
+++ b/java/org/apache/tomcat/dbcp/pool2/impl/ThrowableCallStack.java
@@ -47,7 +47,8 @@ public class ThrowableCallStack implements CallStack {
}
/**
- * Constructs a new instance and use the timestamp as the message with using {@link DateTimeFormatter#ISO_INSTANT} for more precision.
+ * Constructs a new instance and uses the timestamp as the message. The message is the string representation of
+ * the timestamp (see {@link Instant#toString()}).
*
* @param timestamp normally the now instant.
*/
@@ -97,7 +98,7 @@ public class ThrowableCallStack implements CallStack {
message = messageFormat;
} else {
synchronized (dateFormat) {
- // The throwable message is in {@link DateTimeFormatter#ISO_INSTANT} format for more precision.
+ // The timestamp is truncated to milliseconds before it is formatted.
message = dateFormat.format(Long.valueOf(snapshotRef.timestamp.toEpochMilli()));
}
}
diff --git a/java/org/apache/tomcat/jni/SSL.java b/java/org/apache/tomcat/jni/SSL.java
index 8825e2ea20..9bfdaa15e4 100644
--- a/java/org/apache/tomcat/jni/SSL.java
+++ b/java/org/apache/tomcat/jni/SSL.java
@@ -913,8 +913,8 @@ public final class SSL {
* <br>
* The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates
* which are max allowed to be followed while verifying the client certificate. A depth of 0 means that self-signed
- * client certificates are accepted only, the default depth of 1 means the client certificate can be self-signed or
- * has to be signed by a CA which is directly known to the server (i.e. the CA's certificate is under
+ * client certificates are accepted only. A depth of 1 means the client certificate can be self-signed or has to be
+ * signed by a CA which is directly known to the server (i.e. the CA's certificate is under
* {@code setCACertificatePath}, etc).
*
* @param ssl the SSL instance (SSL *)
@@ -973,7 +973,7 @@ public final class SSL {
public static native String[] getCiphers(long ssl);
/**
- * Set the TLSv1.2 and below ciphers available for negotiation the in TLS handshake.
+ * Set the TLSv1.2 and below ciphers available for negotiation in the TLS handshake.
* <p>
* This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to
* configure the ciphers the client is permitted to negotiate in the TLS handshake phase.
@@ -988,7 +988,7 @@ public final class SSL {
public static native boolean setCipherSuites(long ssl, String cipherList) throws Exception;
/**
- * Set the TLSv1.3 cipher suites available for negotiation the in TLS handshake.
+ * Set the TLSv1.3 cipher suites available for negotiation in the TLS handshake.
* <p>
* This uses a colon-separated list of TLSv1.3 cipher suite names in preference order.
*
diff --git a/java/org/apache/tomcat/jni/SSLConf.java b/java/org/apache/tomcat/jni/SSLConf.java
index 755416b29d..89e170c008 100644
--- a/java/org/apache/tomcat/jni/SSLConf.java
+++ b/java/org/apache/tomcat/jni/SSLConf.java
@@ -124,7 +124,7 @@ public final class SSLConf {
*
* @return The result of the native {@code SSL_CONF_CTX_finish} call
*
- * @see <a href="https://www.openssl.org/docs/man1.0.2/ssl/SSL_CONF_CTX_set_flags.html">OpenSSL
+ * @see <a href="https://www.openssl.org/docs/man1.0.2/ssl/SSL_CONF_CTX_finish.html">OpenSSL
* SSL_CONF_CTX_finish</a>
*/
public static native int finish(long cctx);
diff --git a/java/org/apache/tomcat/jni/SSLContext.java b/java/org/apache/tomcat/jni/SSLContext.java
index e1d2940c5e..24dbbfdd64 100644
--- a/java/org/apache/tomcat/jni/SSLContext.java
+++ b/java/org/apache/tomcat/jni/SSLContext.java
@@ -141,7 +141,7 @@ public final class SSLContext {
public static native String[] getCiphers(long ctx);
/**
- * Set the TLSv1.2 and below ciphers available for negotiation the in TLS handshake.
+ * Set the TLSv1.2 and below ciphers available for negotiation in the TLS handshake.
* <p>
* This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to
* configure the ciphers the client is permitted to negotiate in the TLS handshake phase.
@@ -156,7 +156,7 @@ public final class SSLContext {
public static native boolean setCipherSuite(long ctx, String cipherList) throws Exception;
/**
- * Set the TLSv1.3 cipher suites available for negotiation the in TLS handshake.
+ * Set the TLSv1.3 cipher suites available for negotiation in the TLS handshake.
* <p>
* This uses a colon-separated list of TLSv1.3 cipher suite names in preference order.
*
@@ -220,7 +220,7 @@ public final class SSLContext {
* @param ctx Server or Client context to use.
* @param cert Certificate file.
* @param key Private Key file to use if not in cert.
- * @param password Certificate password. If null and certificate is encrypted, password prompt will be displayed.
+ * @param password Certificate password. If null and the certificate is encrypted, loading the certificate will fail.
* @param idx Certificate index SSL_AIDX_RSA or SSL_AIDX_DSA.
*
* @return <code>true</code> if the operation was successful
@@ -276,7 +276,7 @@ public final class SSLContext {
* @param ctx Server or Client context to use.
* @param mode The mode to set
*
- * @return the value set
+ * @return the previous mode
*/
public static native long setSessionCacheMode(long ctx, long mode);
@@ -285,7 +285,7 @@ public final class SSLContext {
*
* @param ctx Server or Client context to use.
*
- * @return the value set
+ * @return the current mode
*/
public static native long getSessionCacheMode(long ctx);
@@ -482,7 +482,7 @@ public final class SSLContext {
public static native void setAlpnProtos(long ctx, String[] alpnProtos, int selectorFailureBehavior);
/**
- * Set the context within which session be reused (server side only)
+ * Set the context within which sessions can be reused (server side only)
* http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html
*
* @param ctx Server context to use.
@@ -495,7 +495,7 @@ public final class SSLContext {
/**
* Set CertificateRaw <br>
- * Use keystore a certificate and key to fill the BIOP
+ * Use a keystore certificate and key to fill the BIO
*
* @param ctx Server or Client context to use.
* @param cert Byte array with the certificate in DER encoding.
@@ -509,7 +509,7 @@ public final class SSLContext {
/**
* Add a certificate to the certificate chain. Certs should be added in order starting with the issuer of the host
* certs and working up the certificate chain to the CA. <br>
- * Use keystore a certificate chain to fill the BIOP
+ * Use a keystore certificate chain to fill the BIO
*
* @param ctx Server or Client context to use.
* @param cert Byte array with the certificate in DER encoding.
diff --git a/java/org/apache/tomcat/util/Diagnostics.java b/java/org/apache/tomcat/util/Diagnostics.java
index 8742a591cc..020b215b69 100644
--- a/java/org/apache/tomcat/util/Diagnostics.java
+++ b/java/org/apache/tomcat/util/Diagnostics.java
@@ -116,7 +116,7 @@ public class Diagnostics {
}
/**
- * Enable or disable thread contention monitoring via the ThreadMxMXBean.
+ * Enable or disable thread contention monitoring via the ThreadMXBean.
*
* @param enable whether to enable thread contention monitoring
*/
@@ -139,7 +139,7 @@ public class Diagnostics {
}
/**
- * Enable or disable thread cpu time measurement via the ThreadMxMXBean.
+ * Enable or disable thread cpu time measurement via the ThreadMXBean.
*
* @param enable whether to enable thread cpu time measurement
*/
diff --git a/java/org/apache/tomcat/util/IntrospectionUtils.java b/java/org/apache/tomcat/util/IntrospectionUtils.java
index 40c38e84c4..75affbf3f1 100644
--- a/java/org/apache/tomcat/util/IntrospectionUtils.java
+++ b/java/org/apache/tomcat/util/IntrospectionUtils.java
@@ -43,8 +43,8 @@ public final class IntrospectionUtils {
}
/**
- * Find a method with the right name If found, call the method ( if param is int or boolean we'll convert value to
- * the right type before) - that means you can have setDebug(1).
+ * Find a method with the right name If found, call the method ( if param is int, long, boolean or
+ * {@code InetAddress} we'll convert value to the right type before) - that means you can have setDebug(1).
*
* @param o The object to set a property on
* @param name The property name
@@ -110,7 +110,7 @@ public final class IntrospectionUtils {
}
}
- // Try a setFoo ( int ) or ( boolean )
+ // Try a setFoo ( int ), ( long ), ( boolean ) or ( InetAddress )
for (Method method : methods) {
boolean ok = true;
if (setter.equals(method.getName()) && method.getParameterTypes().length == 1) {
@@ -328,9 +328,8 @@ public final class IntrospectionUtils {
}
/**
- * Replaces ${NAME} in the value with the value of the property 'NAME'. Replaces ${NAME:DEFAULT} with the value of
- * the property 'NAME:DEFAULT', if the property 'NAME:DEFAULT' is not set, the expression is replaced with the value
- * of the property 'NAME', if the property 'NAME' is not set, the expression is replaced with 'DEFAULT'. If the
+ * Replaces ${NAME} in the value with the value of the property 'NAME'. Replaces ${NAME:-DEFAULT} with the value of
+ * the property 'NAME', if the property 'NAME' is not set, the expression is replaced with 'DEFAULT'. If the
* property is not set and there is no default the value will be returned unmodified.
*
* @param value The value
diff --git a/java/org/apache/tomcat/util/buf/AbstractChunk.java b/java/org/apache/tomcat/util/buf/AbstractChunk.java
index 56e14c0f92..67e1fbc271 100644
--- a/java/org/apache/tomcat/util/buf/AbstractChunk.java
+++ b/java/org/apache/tomcat/util/buf/AbstractChunk.java
@@ -82,7 +82,7 @@ public abstract class AbstractChunk implements Cloneable, Serializable {
/**
- * Maximum amount of data in this buffer. If -1 or not set, the buffer will grow to {{@link #ARRAY_MAX_SIZE}. Can be
+ * Maximum amount of data in this buffer. If -1 or not set, the buffer will grow to {@link #ARRAY_MAX_SIZE}. Can be
* smaller than the current buffer size ( which will not shrink ). When the limit is reached, the buffer will be
* flushed (if out is set) or throw exception.
*
diff --git a/java/org/apache/tomcat/util/buf/ByteChunk.java b/java/org/apache/tomcat/util/buf/ByteChunk.java
index 836c1d0a56..45f9f8f849 100644
--- a/java/org/apache/tomcat/util/buf/ByteChunk.java
+++ b/java/org/apache/tomcat/util/buf/ByteChunk.java
@@ -90,7 +90,7 @@ public final class ByteChunk extends AbstractChunk {
* @param off offset in the bytes array
* @param len length that will be written
*
- * @throws IOException If an I/O occurs while writing the bytes
+ * @throws IOException If an I/O error occurs while writing the bytes
*/
void realWriteBytes(byte[] buf, int off, int len) throws IOException;
@@ -100,7 +100,7 @@ public final class ByteChunk extends AbstractChunk {
*
* @param from bytes that will be written
*
- * @throws IOException If an I/O occurs while writing the bytes
+ * @throws IOException If an I/O error occurs while writing the bytes
*/
void realWriteBytes(ByteBuffer from) throws IOException;
}
@@ -975,14 +975,14 @@ public final class ByteChunk extends AbstractChunk {
/**
- * Returns the first instance of the given bytes in the byte array between the specified start and end.
+ * Returns the first position of any of the given bytes in the byte array between the specified start and end.
*
* @param bytes The byte array to search
* @param start The point to start searching from in the byte array
* @param end The point to stop searching in the byte array
* @param b The array of bytes to search for
*
- * @return The position of the first instance of the byte or -1 if the byte is not found.
+ * @return The position of the first instance of any of the given bytes or -1 if none of them are found.
*/
public static int findBytes(byte[] bytes, int start, int end, byte[] b) {
int offset = start;
diff --git a/java/org/apache/tomcat/util/buf/C2BConverter.java b/java/org/apache/tomcat/util/buf/C2BConverter.java
index 0143a27935..1a37b70cc0 100644
--- a/java/org/apache/tomcat/util/buf/C2BConverter.java
+++ b/java/org/apache/tomcat/util/buf/C2BConverter.java
@@ -42,7 +42,7 @@ public final class C2BConverter {
private CharBuffer cb = null;
/**
- * Leftover buffer used for multi-characters characters.
+ * Leftover buffer used for multi-character characters.
*/
private final CharBuffer leftovers;
diff --git a/java/org/apache/tomcat/util/buf/CharChunk.java b/java/org/apache/tomcat/util/buf/CharChunk.java
index e4f54fa267..a872f33d58 100644
--- a/java/org/apache/tomcat/util/buf/CharChunk.java
+++ b/java/org/apache/tomcat/util/buf/CharChunk.java
@@ -49,7 +49,7 @@ public final class CharChunk extends AbstractChunk implements CharSequence {
public interface CharOutputChannel {
/**
- * Send the bytes ( usually the internal conversion buffer ). Expect 8k output if the buffer is full.
+ * Send the characters ( usually the internal conversion buffer ). Expect 8k output if the buffer is full.
*
* @param buf characters that will be written
* @param off offset in the characters array
@@ -244,7 +244,7 @@ public final class CharChunk extends AbstractChunk implements CharSequence {
// Need more space than we can afford, need to flush buffer.
- // The buffer is already at (or bigger than) limit.
+ // The buffer is below the limit but does not have enough contiguous space for the data to append.
// Optimization:
// If len-avail < length (i.e. after we fill the buffer with what we
@@ -469,7 +469,7 @@ public final class CharChunk extends AbstractChunk implements CharSequence {
/**
- * Compares the message bytes to the specified String object.
+ * Compares the characters in this CharChunk to the specified String object.
*
* @param s the String to compare
*
@@ -492,7 +492,7 @@ public final class CharChunk extends AbstractChunk implements CharSequence {
/**
- * Compares the message bytes to the specified String object.
+ * Compares the characters in this CharChunk to the specified String object, ignoring case.
*
* @param s the String to compare
*
@@ -660,7 +660,7 @@ public final class CharChunk extends AbstractChunk implements CharSequence {
/**
- * Returns the first instance of the given character in this CharChunk starting at the specified char. If the
+ * Returns the first instance of the given character in this CharChunk starting at the specified position. If the
* character is not found, -1 is returned. <br>
*
* @param c The character
diff --git a/java/org/apache/tomcat/util/buf/MessageBytes.java b/java/org/apache/tomcat/util/buf/MessageBytes.java
index 9dbb796e58..5817813699 100644
--- a/java/org/apache/tomcat/util/buf/MessageBytes.java
+++ b/java/org/apache/tomcat/util/buf/MessageBytes.java
@@ -108,6 +108,13 @@ public final class MessageBytes implements Cloneable, Serializable {
return factory.newInstance();
}
+ /**
+ * Creates a shallow clone of this message bytes. The internal byte and char chunks (and any cached String) are
+ * shared with this instance, so the clone is not an independent value.
+ *
+ * @return a shallow clone of this message bytes
+ * @throws CloneNotSupportedException if the object cannot be cloned
+ */
@Override
public Object clone() throws CloneNotSupportedException {
return super.clone();
@@ -539,8 +546,6 @@ public final class MessageBytes implements Cloneable, Serializable {
};
}
- // Inefficient initial implementation. Will be replaced on the next
- // round of tune-up
/**
* Find the index of a string.
* @param s the string
@@ -552,8 +557,6 @@ public final class MessageBytes implements Cloneable, Serializable {
return strValue.indexOf(s, starting);
}
- // Inefficient initial implementation. Will be replaced on the next
- // round of tune-up
/**
* Find the index of a string.
* @param s the string
diff --git a/java/org/apache/tomcat/util/buf/StringCache.java b/java/org/apache/tomcat/util/buf/StringCache.java
index 423de39eef..c7b762f1b5 100644
--- a/java/org/apache/tomcat/util/buf/StringCache.java
+++ b/java/org/apache/tomcat/util/buf/StringCache.java
@@ -312,8 +312,8 @@ public class StringCache {
size = cacheSize;
}
ByteEntry[] tempbcCache = new ByteEntry[size];
- // Fill it up using an alphabetical order
- // and a dumb insert sort
+ // Fill it up in descending order of occurrence count, breaking ties in alphabetical order,
+ // using a dumb insert sort
ByteChunk tempChunk = new ByteChunk();
int n = 0;
while (n < size) {
@@ -426,8 +426,8 @@ public class StringCache {
size = cacheSize;
}
CharEntry[] tempccCache = new CharEntry[size];
- // Fill it up using an alphabetical order
- // and a dumb insert sort
+ // Fill it up in descending order of occurrence count, breaking ties in alphabetical order,
+ // using a dumb insert sort
CharChunk tempChunk = new CharChunk();
int n = 0;
while (n < size) {
diff --git a/java/org/apache/tomcat/util/buf/UDecoder.java b/java/org/apache/tomcat/util/buf/UDecoder.java
index 0c84e6ba87..0d2d87bc46 100644
--- a/java/org/apache/tomcat/util/buf/UDecoder.java
+++ b/java/org/apache/tomcat/util/buf/UDecoder.java
@@ -33,7 +33,7 @@ import org.apache.tomcat.util.res.StringManager;
public final class UDecoder {
/**
- * Constructs a new UDecoder. This utility class should not be instantiated.
+ * Constructs a new UDecoder.
*/
public UDecoder() {
}
diff --git a/java/org/apache/tomcat/util/buf/UEncoder.java b/java/org/apache/tomcat/util/buf/UEncoder.java
index 7007046182..ec9051b20f 100644
--- a/java/org/apache/tomcat/util/buf/UEncoder.java
+++ b/java/org/apache/tomcat/util/buf/UEncoder.java
@@ -78,7 +78,8 @@ public final class UEncoder {
* @param start the beginning index, inclusive
* @param end the ending index, exclusive
*
- * @return A new CharChunk contained the URL encoded string
+ * @return the URL encoded string in an internal {@link CharChunk} that is recycled at the start of the next
+ * {@code encodeURL} call. The content must be copied before invoking {@code encodeURL} again.
*
* @throws IOException If an I/O error occurs
*/
diff --git a/java/org/apache/tomcat/util/buf/UriUtil.java b/java/org/apache/tomcat/util/buf/UriUtil.java
index 91ed37d1b8..0d6bb83aba 100644
--- a/java/org/apache/tomcat/util/buf/UriUtil.java
+++ b/java/org/apache/tomcat/util/buf/UriUtil.java
@@ -70,7 +70,8 @@ public final class UriUtil {
/**
- * Determine if the character is allowed in the scheme of a URI. See RFC 2396, Section 3.1
+ * Determine if the character is allowed in the scheme of a URI. See RFC 2396, Section 3.1. Note that this method
+ * is more permissive than RFC 2396 which requires the first scheme character to be an alpha.
*
* @param c The character to test
*
diff --git a/java/org/apache/tomcat/util/collections/ConcurrentCache.java b/java/org/apache/tomcat/util/collections/ConcurrentCache.java
index 901799390e..de26780873 100644
--- a/java/org/apache/tomcat/util/collections/ConcurrentCache.java
+++ b/java/org/apache/tomcat/util/collections/ConcurrentCache.java
@@ -22,7 +22,7 @@ import java.util.concurrent.ConcurrentHashMap;
/**
* A thread-safe cache that uses an eden space backed by a {@link ConcurrentHashMap}
- * and a long-term space backed by a {@link WeakHashMap}. When the eden space exceeds
+ * and a long-term space backed by a {@link WeakHashMap}. When the eden space reaches
* the configured size, its contents are promoted to the long-term space.
*
* @param <K> the key type
diff --git a/java/org/apache/tomcat/util/compat/JreCompat.java b/java/org/apache/tomcat/util/compat/JreCompat.java
index be005d511d..79e97050c7 100644
--- a/java/org/apache/tomcat/util/compat/JreCompat.java
+++ b/java/org/apache/tomcat/util/compat/JreCompat.java
@@ -38,7 +38,7 @@ public class JreCompat {
Class<?> nativeImageClazz = Class.forName("org.graalvm.nativeimage.ImageInfo");
result = Boolean.TRUE.equals(nativeImageClazz.getMethod("inImageCode").invoke(null));
} catch (ClassNotFoundException e) {
- // Must be Graal
+ // Not running on a GraalVM native image
} catch (ReflectiveOperationException | IllegalArgumentException e) {
// Should never happen
}
diff --git a/java/org/apache/tomcat/util/compat/JrePlatform.java b/java/org/apache/tomcat/util/compat/JrePlatform.java
index 33ecac8333..7058e67f3b 100644
--- a/java/org/apache/tomcat/util/compat/JrePlatform.java
+++ b/java/org/apache/tomcat/util/compat/JrePlatform.java
@@ -24,7 +24,8 @@ import java.util.Locale;
public class JrePlatform {
/**
- * Constructs a new JrePlatform instance. This class cannot be instantiated.
+ * Constructs a new JrePlatform instance. The platform flags are static;
+ * instances carry no state.
*/
public JrePlatform() {
}
diff --git a/java/org/apache/tomcat/util/compat/JreVendor.java b/java/org/apache/tomcat/util/compat/JreVendor.java
index a4322a3299..7f5d4555d1 100644
--- a/java/org/apache/tomcat/util/compat/JreVendor.java
+++ b/java/org/apache/tomcat/util/compat/JreVendor.java
@@ -24,7 +24,8 @@ import java.util.Locale;
public class JreVendor {
/**
- * Constructs a new JreVendor instance. This class cannot be instantiated.
+ * Constructs a new JreVendor instance. The vendor flags are static;
+ * instances carry no state.
*/
public JreVendor() {
}
diff --git a/java/org/apache/tomcat/util/concurrent/KeyedReentrantReadWriteLock.java b/java/org/apache/tomcat/util/concurrent/KeyedReentrantReadWriteLock.java
index c5b79d9cce..03e8ca4871 100644
--- a/java/org/apache/tomcat/util/concurrent/KeyedReentrantReadWriteLock.java
+++ b/java/org/apache/tomcat/util/concurrent/KeyedReentrantReadWriteLock.java
@@ -100,7 +100,7 @@ public class KeyedReentrantReadWriteLock {
/*
* Lock wrapper implementation that provides both read locks and write locks from the underlying lock and tracks
- * their usage. Most of the methods throw UnsupportedOperationException as Tomcat does not (currently) require
+ * their usage. All other methods throw UnsupportedOperationException as Tomcat does not (currently) require
* implementations of those methods.
*/
private static class LockImpl implements Lock {
diff --git a/java/org/apache/tomcat/util/descriptor/DigesterFactory.java b/java/org/apache/tomcat/util/descriptor/DigesterFactory.java
index 051f88cf10..4259e653ca 100644
--- a/java/org/apache/tomcat/util/descriptor/DigesterFactory.java
+++ b/java/org/apache/tomcat/util/descriptor/DigesterFactory.java
@@ -31,7 +31,7 @@ import org.apache.tomcat.util.res.StringManager;
import org.xml.sax.ext.EntityResolver2;
/**
- * Wrapper class around the Digester that hide Digester's initialization details.
+ * Wrapper class around the Digester that hides Digester's initialization details.
*/
public class DigesterFactory {
@@ -59,7 +59,8 @@ public class DigesterFactory {
/**
- * Mapping of well-known public IDs used by the Servlet API to the matching local resource.
+ * Mapping of well-known public IDs used by the Servlet API and the W3C XML
+ * schemas to the matching local resource.
*/
public static final Map<String,String> SERVLET_API_PUBLIC_IDS;
diff --git a/java/org/apache/tomcat/util/descriptor/LocalResolver.java b/java/org/apache/tomcat/util/descriptor/LocalResolver.java
index 6f2d616ea6..cb442e6802 100644
--- a/java/org/apache/tomcat/util/descriptor/LocalResolver.java
+++ b/java/org/apache/tomcat/util/descriptor/LocalResolver.java
@@ -50,7 +50,7 @@ public class LocalResolver implements EntityResolver2 {
*
* @param publicIds mapping of well-known public identifiers to local resources
* @param systemIds mapping of well-known system identifiers to local resources
- * @param blockExternal are external resources blocked that are not well-known
+ * @param blockExternal whether external resources that are not well-known are blocked
*/
public LocalResolver(Map<String,String> publicIds, Map<String,String> systemIds, boolean blockExternal) {
this.publicIds = publicIds;
diff --git a/java/org/apache/tomcat/util/descriptor/tagplugin/TagPluginParser.java b/java/org/apache/tomcat/util/descriptor/tagplugin/TagPluginParser.java
index 676a18330d..d9c4be8ca9 100644
--- a/java/org/apache/tomcat/util/descriptor/tagplugin/TagPluginParser.java
+++ b/java/org/apache/tomcat/util/descriptor/tagplugin/TagPluginParser.java
@@ -85,15 +85,16 @@ public class TagPluginParser {
/**
* Registers a plugin class for the given tag class.
*
- * @param tagClass the tag handler class name
- * @param pluginClass the plugin class name
+ * @param tagClass the tag handler class name. Must not be {@code null}.
+ * @param pluginClass the plugin class name. Must not be {@code null}.
*/
public void addPlugin(String tagClass, String pluginClass) {
plugins.put(tagClass, pluginClass);
}
/**
- * Returns the map of registered tag plugins.
+ * Returns the map of registered tag plugins. The returned map is the parser's internal mutable map, so changes to
+ * it change the parser's state.
*
* @return the map from tag class names to plugin class names
*/
diff --git a/java/org/apache/tomcat/util/descriptor/tld/ImplicitTldRuleSet.java b/java/org/apache/tomcat/util/descriptor/tld/ImplicitTldRuleSet.java
index 3f40bff77c..10e7882fd5 100644
--- a/java/org/apache/tomcat/util/descriptor/tld/ImplicitTldRuleSet.java
+++ b/java/org/apache/tomcat/util/descriptor/tld/ImplicitTldRuleSet.java
@@ -23,7 +23,7 @@ import org.apache.tomcat.util.res.StringManager;
import org.xml.sax.Attributes;
/**
- * RulesSet for digesting implicit.tld files. Only version information used and short names are allowed.
+ * RuleSet for digesting implicit.tld files. Only version information used and short names are allowed.
*/
public class ImplicitTldRuleSet implements RuleSet {
diff --git a/java/org/apache/tomcat/util/descriptor/tld/TagFileXml.java b/java/org/apache/tomcat/util/descriptor/tld/TagFileXml.java
index 32651f8677..e1a3361736 100644
--- a/java/org/apache/tomcat/util/descriptor/tld/TagFileXml.java
+++ b/java/org/apache/tomcat/util/descriptor/tld/TagFileXml.java
@@ -17,7 +17,7 @@
package org.apache.tomcat.util.descriptor.tld;
/**
- * Bare-bone model of a tag file loaded from a TLD. This does not contain the tag-specific attributes that requiring
+ * Bare-bone model of a tag file loaded from a TLD. This does not contain the tag-specific attributes that require
* parsing the actual tag file to derive.
*/
public class TagFileXml {
diff --git a/java/org/apache/tomcat/util/descriptor/tld/TagXml.java b/java/org/apache/tomcat/util/descriptor/tld/TagXml.java
index e4e54517d8..0dde639d10 100644
--- a/java/org/apache/tomcat/util/descriptor/tld/TagXml.java
+++ b/java/org/apache/tomcat/util/descriptor/tld/TagXml.java
@@ -24,7 +24,7 @@ import jakarta.servlet.jsp.tagext.TagInfo;
import jakarta.servlet.jsp.tagext.TagVariableInfo;
/**
- * Model of a tag define in a tag library descriptor. This represents the information as parsed from the XML but differs
+ * Model of a tag defined in a tag library descriptor. This represents the information as parsed from the XML but differs
* from TagInfo in that it does not provide a link back to the tag library that defined it.
*/
public class TagXml {
diff --git a/java/org/apache/tomcat/util/descriptor/tld/TldRuleSet.java b/java/org/apache/tomcat/util/descriptor/tld/TldRuleSet.java
index d53753a575..93052df0dd 100644
--- a/java/org/apache/tomcat/util/descriptor/tld/TldRuleSet.java
+++ b/java/org/apache/tomcat/util/descriptor/tld/TldRuleSet.java
@@ -319,7 +319,7 @@ public class TldRuleSet implements RuleSet {
*/
public TagAttributeInfo toTagAttributeInfo() {
if (fragment) {
- // JSP8.5.2: for a fragment type is fixed and rexprvalue is true
+ // JSP spec 8.5.2: for a fragment the type is fixed and rtexprvalue is true
type = "jakarta.servlet.jsp.tagext.JspFragment";
requestTime = true;
} else if (deferredValue) {
diff --git a/java/org/apache/tomcat/util/descriptor/web/ApplicationParameter.java b/java/org/apache/tomcat/util/descriptor/web/ApplicationParameter.java
index 925fe03382..fe8ed00d54 100644
--- a/java/org/apache/tomcat/util/descriptor/web/ApplicationParameter.java
+++ b/java/org/apache/tomcat/util/descriptor/web/ApplicationParameter.java
@@ -40,7 +40,7 @@ public class ApplicationParameter implements Serializable {
/**
- * The description of this environment entry.
+ * The description of this context initialization parameter.
*/
private String description = null;
diff --git a/java/org/apache/tomcat/util/descriptor/web/ContextResource.java b/java/org/apache/tomcat/util/descriptor/web/ContextResource.java
index d5b51f99be..1882e9dcdd 100644
--- a/java/org/apache/tomcat/util/descriptor/web/ContextResource.java
+++ b/java/org/apache/tomcat/util/descriptor/web/ContextResource.java
@@ -61,12 +61,12 @@ public class ContextResource extends ResourceBase {
}
/**
- * The sharing scope of this resource factory (<code>Shareable</code> or <code>Unshareable</code>).
+ * The sharing scope of this resource (<code>Shareable</code> or <code>Unshareable</code>).
*/
private String scope = "Shareable";
/**
- * Returns the sharing scope of this resource factory.
+ * Returns the sharing scope of this resource.
*
* @return the sharing scope
*/
@@ -75,7 +75,7 @@ public class ContextResource extends ResourceBase {
}
/**
- * Sets the sharing scope of this resource factory.
+ * Sets the sharing scope of this resource.
*
* @param scope the sharing scope
*/
diff --git a/java/org/apache/tomcat/util/descriptor/web/ContextResourceEnvRef.java b/java/org/apache/tomcat/util/descriptor/web/ContextResourceEnvRef.java
index aa5b623be6..4ac430d68c 100644
--- a/java/org/apache/tomcat/util/descriptor/web/ContextResourceEnvRef.java
+++ b/java/org/apache/tomcat/util/descriptor/web/ContextResourceEnvRef.java
@@ -37,12 +37,12 @@ public class ContextResourceEnvRef extends ResourceBase {
// ------------------------------------------------------------- Properties
/**
- * Does this environment entry allow overrides by the application deployment descriptor?
+ * Does this resource-env-ref allow overrides by the application deployment descriptor?
*/
private boolean override = true;
/**
- * Returns whether this environment entry allows overrides by the application deployment descriptor.
+ * Returns whether this resource-env-ref allows overrides by the application deployment descriptor.
*
* @return true if overrides are allowed
*/
@@ -51,7 +51,7 @@ public class ContextResourceEnvRef extends ResourceBase {
}
/**
- * Sets whether this environment entry allows overrides by the application deployment descriptor.
+ * Sets whether this resource-env-ref allows overrides by the application deployment descriptor.
*
* @param override true if overrides are allowed
*/
diff --git a/java/org/apache/tomcat/util/descriptor/web/ContextTransaction.java b/java/org/apache/tomcat/util/descriptor/web/ContextTransaction.java
index dba1528b9a..f131edc795 100644
--- a/java/org/apache/tomcat/util/descriptor/web/ContextTransaction.java
+++ b/java/org/apache/tomcat/util/descriptor/web/ContextTransaction.java
@@ -24,8 +24,8 @@ import java.util.Map;
/**
- * Representation of an application resource reference, as represented in an <code><res-env-ref></code> element in
- * the deployment descriptor.
+ * Representation of a <code><Transaction></code> element in a context configuration file. The configured
+ * properties are applied to the <code>java:comp/UserTransaction</code> JNDI binding.
*/
public class ContextTransaction implements Serializable {
diff --git a/java/org/apache/tomcat/util/descriptor/web/ErrorPage.java b/java/org/apache/tomcat/util/descriptor/web/ErrorPage.java
index d2fb728ef0..34d85d00e5 100644
--- a/java/org/apache/tomcat/util/descriptor/web/ErrorPage.java
+++ b/java/org/apache/tomcat/util/descriptor/web/ErrorPage.java
@@ -82,7 +82,7 @@ public class ErrorPage implements Serializable {
/**
- * Set the error code (hack for default XmlMapper data type).
+ * Set the error code, parsing the provided string value.
*
* @param errorCode The new error code
*/
diff --git a/java/org/apache/tomcat/util/descriptor/web/FilterMap.java b/java/org/apache/tomcat/util/descriptor/web/FilterMap.java
index f6c147fb7d..2f058d7316 100644
--- a/java/org/apache/tomcat/util/descriptor/web/FilterMap.java
+++ b/java/org/apache/tomcat/util/descriptor/web/FilterMap.java
@@ -220,7 +220,7 @@ public class FilterMap implements Serializable {
// apply ERROR to the global dispatcherMapping.
dispatcherMapping |= ERROR;
} else if (dispatcher.equals(DispatcherType.ASYNC.name())) {
- // apply ERROR to the global dispatcherMapping.
+ // apply ASYNC to the global dispatcherMapping.
dispatcherMapping |= ASYNC;
}
}
diff --git a/java/org/apache/tomcat/util/descriptor/web/Injectable.java b/java/org/apache/tomcat/util/descriptor/web/Injectable.java
index d3bc8d914d..95a6da0a8e 100644
--- a/java/org/apache/tomcat/util/descriptor/web/Injectable.java
+++ b/java/org/apache/tomcat/util/descriptor/web/Injectable.java
@@ -32,8 +32,8 @@ public interface Injectable {
/**
* Adds an injection target to this injectable.
*
- * @param injectionTargetName the name of the injection target
- * @param jndiName the JNDI name for the injection
+ * @param injectionTargetName the class name of the injection target
+ * @param jndiName the name of the field or method the resource is injected into
*/
void addInjectionTarget(String injectionTargetName, String jndiName);
diff --git a/java/org/apache/tomcat/util/descriptor/web/ResourceBase.java b/java/org/apache/tomcat/util/descriptor/web/ResourceBase.java
index daca36ff01..4406e0d017 100644
--- a/java/org/apache/tomcat/util/descriptor/web/ResourceBase.java
+++ b/java/org/apache/tomcat/util/descriptor/web/ResourceBase.java
@@ -26,7 +26,8 @@ import java.util.Map;
/**
- * Representation of a Context element.
+ * Common base class for the JNDI resource entries (e.g. <code><resource-ref></code>,
+ * <code><message-destination-ref></code>) of a web deployment descriptor.
*/
public class ResourceBase implements Serializable, Injectable {
/**
diff --git a/java/org/apache/tomcat/util/descriptor/web/SecurityConstraint.java b/java/org/apache/tomcat/util/descriptor/web/SecurityConstraint.java
index 0e734dad47..2a537e3292 100644
--- a/java/org/apache/tomcat/util/descriptor/web/SecurityConstraint.java
+++ b/java/org/apache/tomcat/util/descriptor/web/SecurityConstraint.java
@@ -311,8 +311,9 @@ public class SecurityConstraint implements Serializable {
/**
* Return the set of roles that are permitted access to the resources protected by this security constraint. If none
- * have been defined, a zero-length array is returned (which implies that all authenticated users are permitted
- * access).
+ * have been defined, a zero-length array is returned. A zero-length array implies that all authenticated users are
+ * permitted access only if {@link #getAuthConstraint()} returns {@code false}; if it returns {@code true}, a
+ * zero-length array means that no user is permitted access.
*
* @return the roles array
*/
diff --git a/java/org/apache/tomcat/util/descriptor/web/ServletDef.java b/java/org/apache/tomcat/util/descriptor/web/ServletDef.java
index 6b7daddac6..e5a65be7a9 100644
--- a/java/org/apache/tomcat/util/descriptor/web/ServletDef.java
+++ b/java/org/apache/tomcat/util/descriptor/web/ServletDef.java
@@ -223,7 +223,7 @@ public class ServletDef implements Serializable {
private final Map<String,String> parameters = new HashMap<>();
/**
- * Returns the set of initialization parameters for this servlet, keyed by parameter name.
+ * Returns the map of initialization parameters for this servlet, keyed by parameter name.
*
* @return the parameter map
*/
diff --git a/java/org/apache/tomcat/util/descriptor/web/WebXml.java b/java/org/apache/tomcat/util/descriptor/web/WebXml.java
index 95b3cb5215..a27943d2a3 100644
--- a/java/org/apache/tomcat/util/descriptor/web/WebXml.java
+++ b/java/org/apache/tomcat/util/descriptor/web/WebXml.java
@@ -252,9 +252,10 @@ public class WebXml {
}
/**
- * Set the version for this web.xml file
+ * Set the version for this web.xml file. Values of <code>null</code> are ignored. Unrecognised version strings
+ * only log a warning and the version is left unchanged (defaulting to 6.2 if not previously set).
*
- * @param version Values of <code>null</code> will be ignored
+ * @param version the version
*/
public void setVersion(String version) {
if (version == null) {
@@ -1348,13 +1349,13 @@ public class WebXml {
// TODO - Various, icon, description etc elements are skipped - mainly
// because they are ignored when web.xml is parsed - see above
- // NOTE - Elements need to be written in the order defined in the 2.3
- // DTD else validation of the merged web.xml will fail
+ // NOTE - Elements need to be written in the order defined in the
+ // schema for the version in use else validation of the merged web.xml
+ // will fail
// NOTE - Some elements need to be skipped based on the version of the
- // specification being used. Version is validated and starts at
- // 2.2. The version tests used in this method take advantage of
- // this.
+ // specification being used. The version tests used in this method take
+ // advantage of this.
// Declaration
sb.append("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
diff --git a/java/org/apache/tomcat/util/descriptor/web/mbeans-descriptors.xml b/java/org/apache/tomcat/util/descriptor/web/mbeans-descriptors.xml
index 90dab0df5c..258ffab292 100644
--- a/java/org/apache/tomcat/util/descriptor/web/mbeans-descriptors.xml
+++ b/java/org/apache/tomcat/util/descriptor/web/mbeans-descriptors.xml
@@ -75,7 +75,7 @@
type="java.lang.String"/>
<attribute name="scope"
- description="The sharing scope of this resource factory"
+ description="The sharing scope of this resource"
type="java.lang.String"/>
<attribute name="type"
diff --git a/java/org/apache/tomcat/util/digester/AbstractObjectCreationFactory.java b/java/org/apache/tomcat/util/digester/AbstractObjectCreationFactory.java
index f2065057d9..e59bdac041 100644
--- a/java/org/apache/tomcat/util/digester/AbstractObjectCreationFactory.java
+++ b/java/org/apache/tomcat/util/digester/AbstractObjectCreationFactory.java
@@ -38,7 +38,8 @@ public abstract class AbstractObjectCreationFactory implements ObjectCreationFac
/**
- * The associated <code>Digester</code> instance that was set up by {@link FactoryCreateRule} upon initialization.
+ * The associated <code>Digester</code> instance that was set by {@link Digester#addFactoryCreate} upon
+ * initialization.
*/
private Digester digester = null;
@@ -60,7 +61,7 @@ public abstract class AbstractObjectCreationFactory implements ObjectCreationFac
/**
* <p>
- * Returns the {@link Digester} that was set by the {@link FactoryCreateRule} upon initialization.
+ * Returns the {@link Digester} that was set by {@link Digester#addFactoryCreate} upon initialization.
*/
@Override
public Digester getDigester() {
diff --git a/java/org/apache/tomcat/util/digester/ArrayStack.java b/java/org/apache/tomcat/util/digester/ArrayStack.java
index 6f63b4f885..fb6a533814 100644
--- a/java/org/apache/tomcat/util/digester/ArrayStack.java
+++ b/java/org/apache/tomcat/util/digester/ArrayStack.java
@@ -26,11 +26,6 @@ import java.util.EmptyStackException;
* from Digester.
* </p>
* <p>
- * <strong>WARNING</strong> - This class is public solely to allow it to be used from subpackages of
- * <code>org.apache.commons.digester</code>. It should not be considered part of the public API of Commons Digester. If
- * you want to use such a class yourself, you should use the one from Commons Collections directly.
- * </p>
- * <p>
* An implementation of the {@link java.util.Stack} API that is based on an <code>ArrayList</code> instead of a
* <code>Vector</code>, so it is not synchronized to protect against multi-threaded access. The implementation is
* therefore operates faster in environments where you do not need to worry about multiple thread contention.
diff --git a/java/org/apache/tomcat/util/digester/CallMethodRule.java b/java/org/apache/tomcat/util/digester/CallMethodRule.java
index 9199ff415d..c475df0ebe 100644
--- a/java/org/apache/tomcat/util/digester/CallMethodRule.java
+++ b/java/org/apache/tomcat/util/digester/CallMethodRule.java
@@ -30,15 +30,13 @@ import org.xml.sax.Attributes;
* By using {@link #CallMethodRule(String methodName)} a method call can be made to a method which accepts no arguments.
* </p>
* <p>
- * Incompatible method parameter types are converted using <code>org.apache.commons.beanutils.ConvertUtils</code>.
+ * Incompatible method parameter types are converted using
+ * <code>org.apache.tomcat.util.introspection.IntrospectionUtils#convert</code>.
* </p>
* <p>
- * This rule now uses
- * <a href="https://commons.apache.org/beanutils/apidocs/org/apache/commons/beanutils/MethodUtils.html">
- * org.apache.commons.beanutils.MethodUtils#invokeMethod </a> by default. This increases the kinds of methods
- * successfully and allows primitives to be matched by passing in wrapper classes. There are rare cases when
- * org.apache.commons.beanutils.MethodUtils#invokeExactMethod (the old default) is required. This method is much
- * stricter in its reflection. Setting the <code>UseExactMatch</code> to true reverts to the use of this method.
+ * The target method is invoked using
+ * <code>org.apache.tomcat.util.introspection.IntrospectionUtils#callMethodN</code> which allows primitives to be
+ * matched by passing in wrapper classes.
* </p>
* <p>
* Note that the target method is invoked when the <i>end</i> of the tag the CallMethodRule fired on is encountered,
@@ -105,16 +103,16 @@ public class CallMethodRule extends Rule {
/**
- * Construct a "call method" rule with the specified method name and parameter types. If <code>paramCount</code> is
- * set to zero the rule will use the body of this element as the single argument of the method, unless
- * <code>paramTypes</code> is null or empty, in this case the rule will call the specified method with no arguments.
+ * Construct a "call method" rule with the specified method name and parameter types. If <code>paramTypes</code> is
+ * <code>null</code>, <code>paramCount</code> String parameters are collected. Otherwise, the number of parameters
+ * is taken from <code>paramTypes</code> and <code>paramCount</code> is ignored.
*
* @param targetOffset location of the target object. Positive numbers are relative to the top of the digester
* object stack. Negative numbers are relative to the bottom of the stack. Zero implies the
* top object on the stack.
* @param methodName Method name of the parent method to call
- * @param paramCount The number of parameters to collect, or zero for a single argument from the body of this
- * element
+ * @param paramCount The number of String parameters to collect when <code>paramTypes</code> is
+ * <code>null</code>
* @param paramTypes The Java classes that represent the parameter types of the method arguments (if you wish to
* use a primitive type, specify the corresponding Java wrapper class instead, such as
* <code>java.lang.Boolean.TYPE</code> for a <code>boolean</code> parameter)
diff --git a/java/org/apache/tomcat/util/digester/CallParamRule.java b/java/org/apache/tomcat/util/digester/CallParamRule.java
index c6da747243..962f02cde4 100644
--- a/java/org/apache/tomcat/util/digester/CallParamRule.java
+++ b/java/org/apache/tomcat/util/digester/CallParamRule.java
@@ -27,7 +27,7 @@ import org.xml.sax.Attributes;
* </p>
* <ul>
* <li>from an attribute of the current element See {@link #CallParamRule(int paramIndex, String attributeName)}
- * <li>from current the element body See {@link #CallParamRule(int paramIndex)}
+ * <li>from the element body See {@link #CallParamRule(int paramIndex)}
* </ul>
*/
public class CallParamRule extends Rule {
diff --git a/java/org/apache/tomcat/util/digester/Digester.java b/java/org/apache/tomcat/util/digester/Digester.java
index ede0f03395..f79f72fbd9 100644
--- a/java/org/apache/tomcat/util/digester/Digester.java
+++ b/java/org/apache/tomcat/util/digester/Digester.java
@@ -73,10 +73,6 @@ import org.xml.sax.helpers.AttributesImpl;
* thread at a time, and a call to <code>parse()</code> must be completed before another can be initiated even from the
* same thread.
* </p>
- * <p>
- * <strong>IMPLEMENTATION NOTE</strong> - A bug in Xerces 2.0.2 prevents the support of XML schema. You need Xerces
- * 2.1/2.3 and up to make this class working with XML schema
- * </p>
*/
public class Digester extends DefaultHandler2 {
@@ -646,7 +642,7 @@ public class Digester extends DefaultHandler2 {
/**
- * Sets a flag indicating whether the requested feature is supported by the underlying implementation of
+ * Sets the value of the requested feature in the underlying implementation of
* <code>org.xml.sax.XMLReader</code>. See
* <a href="http://www.saxproject.org/apidoc/xml/sax/package-summary.html#package-description">
* http://www.saxproject.org/apidoc/xml/sax/package-summary.html#package-description</a> for information about the
@@ -949,8 +945,7 @@ public class Digester extends DefaultHandler2 {
/**
- * Return the XMLReader to be used for parsing the input document. FIX ME: there is a bug in JAXP/XERCES that
- * prevent the use of a parser that contains a schema with a DTD.
+ * Return the XMLReader to be used for parsing the input document.
*
* @return the XML reader
*
@@ -1288,7 +1283,7 @@ public class Digester extends DefaultHandler2 {
* processing is not being performed.
* @param localName The local name (without prefix), or the empty string if Namespace processing is not being
* performed.
- * @param qName The qualified name (with prefix), or the empty string if qualified names are not available.\
+ * @param qName The qualified name (with prefix), or the empty string if qualified names are not available.
* @param list The attributes attached to the element. If there are no attributes, it shall be an empty
* Attributes object.
*
diff --git a/java/org/apache/tomcat/util/digester/ObjectCreationFactory.java b/java/org/apache/tomcat/util/digester/ObjectCreationFactory.java
index 9c219fd5a5..69f97d0d5f 100644
--- a/java/org/apache/tomcat/util/digester/ObjectCreationFactory.java
+++ b/java/org/apache/tomcat/util/digester/ObjectCreationFactory.java
@@ -44,7 +44,7 @@ public interface ObjectCreationFactory {
/**
* Gets the digester that was set upon initialization.
*
- * @return the {@link Digester} that was set by the {@link FactoryCreateRule} upon initialization.
+ * @return the {@link Digester} that was set by {@link Digester#addFactoryCreate} upon initialization.
*/
Digester getDigester();
diff --git a/java/org/apache/tomcat/util/digester/Rule.java b/java/org/apache/tomcat/util/digester/Rule.java
index e5c2be12b1..fd7f734217 100644
--- a/java/org/apache/tomcat/util/digester/Rule.java
+++ b/java/org/apache/tomcat/util/digester/Rule.java
@@ -118,8 +118,8 @@ public abstract class Rule {
/**
- * This method is called when the body of a matching XML element is encountered. If the element has no body, this
- * method is not called at all. The default implementation is a NO-OP.
+ * This method is called when the body of a matching XML element is encountered. The method is also called for
+ * elements with no body, in which case the text is an empty string. The default implementation is a NO-OP.
*
* @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
* aware or the element has no namespace
diff --git a/java/org/apache/tomcat/util/digester/RuleSet.java b/java/org/apache/tomcat/util/digester/RuleSet.java
index 5527fda803..8d2010934b 100644
--- a/java/org/apache/tomcat/util/digester/RuleSet.java
+++ b/java/org/apache/tomcat/util/digester/RuleSet.java
@@ -18,14 +18,11 @@ package org.apache.tomcat.util.digester;
/**
* <p>
- * Public interface defining a shorthand means of configuring a complete set of related <code>Rule</code> definitions,
- * possibly associated with a particular namespace URI, in one operation. To use an instance of a class that implements
- * this interface:
+ * Public interface defining a shorthand means of configuring a complete set of related <code>Rule</code> definitions
+ * in one operation. To use an instance of a class that implements this interface:
* </p>
* <ul>
* <li>Create a concrete implementation of this interface.</li>
- * <li>Optionally, you can configure a <code>RuleSet</code> to be relevant only for a particular namespace URI by
- * configuring the value to be returned by <code>getNamespaceURI()</code>.</li>
* <li>As you are configuring your Digester instance, call <code>digester.addRuleSet()</code> and pass the RuleSet
* instance.</li>
* <li>Digester will call the <code>addRuleInstances()</code> method of your RuleSet to configure the necessary
diff --git a/java/org/apache/tomcat/util/digester/RulesBase.java b/java/org/apache/tomcat/util/digester/RulesBase.java
index 72bf54f78f..1cb30cc623 100644
--- a/java/org/apache/tomcat/util/digester/RulesBase.java
+++ b/java/org/apache/tomcat/util/digester/RulesBase.java
@@ -131,11 +131,12 @@ public class RulesBase implements Rules {
* @param namespaceURI Namespace URI for which to select matching rules, or <code>null</code> to match regardless of
* namespace URI
* @param pattern Nesting pattern to be matched
+ *
+ * @return a rules list
*/
@Override
public List<Rule> match(String namespaceURI, String pattern) {
- // List rulesList = (List) this.cache.get(pattern);
List<Rule> rulesList = lookup(namespaceURI, pattern);
if ((rulesList == null) || (rulesList.isEmpty())) {
// Find the longest key, ie more discriminant
@@ -144,7 +145,6 @@ public class RulesBase implements Rules {
if (key.startsWith("*/")) {
if (pattern.equals(key.substring(2)) || pattern.endsWith(key.substring(1))) {
if (key.length() > longKey.length()) {
- // rulesList = (List) this.cache.get(key);
rulesList = lookup(namespaceURI, key);
longKey = key;
}
diff --git a/java/org/apache/tomcat/util/file/ConfigFileLoader.java b/java/org/apache/tomcat/util/file/ConfigFileLoader.java
index b48318ac07..9bb0c9e583 100644
--- a/java/org/apache/tomcat/util/file/ConfigFileLoader.java
+++ b/java/org/apache/tomcat/util/file/ConfigFileLoader.java
@@ -28,7 +28,7 @@ public class ConfigFileLoader {
private static ConfigurationSource source;
/**
- * Get the configured configuration source. If none has been configured, a default source based on the calling
+ * Get the configured configuration source. If none has been configured, a default source based on the JVM working
* directory will be used.
*
* @return the configuration source in use
@@ -41,7 +41,8 @@ public class ConfigFileLoader {
}
/**
- * Set the configuration source used by Tomcat to locate various configuration resources.
+ * Set the configuration source used by Tomcat to locate various configuration resources. Only the first call has
+ * an effect; subsequent calls are ignored.
*
* @param source The source
*/
diff --git a/java/org/apache/tomcat/util/file/Matcher.java b/java/org/apache/tomcat/util/file/Matcher.java
index 9ea0d3afe3..b3db24df86 100644
--- a/java/org/apache/tomcat/util/file/Matcher.java
+++ b/java/org/apache/tomcat/util/file/Matcher.java
@@ -25,7 +25,7 @@ import java.util.Set;
* org.apache.tools.ant.types.selectors.SelectorUtils.
* </p>
* <p>
- * All methods are static.
+ * All methods are static; instances of this class carry no state.
* </p>
*/
public final class Matcher {
@@ -165,7 +165,7 @@ public final class Matcher {
return allStars(patArr, patIdxStart, patIdxEnd);
}
- // process pattern between stars. padIdxStart and patIdxEnd point
+ // process pattern between stars. patIdxStart and patIdxEnd point
// always to a '*'.
while (patIdxStart != patIdxEnd && strIdxStart <= strIdxEnd) {
int patIdxTmp = -1;
diff --git a/java/org/apache/tomcat/util/http/CookieProcessor.java b/java/org/apache/tomcat/util/http/CookieProcessor.java
index ad1afa9a71..668bd53045 100644
--- a/java/org/apache/tomcat/util/http/CookieProcessor.java
+++ b/java/org/apache/tomcat/util/http/CookieProcessor.java
@@ -41,8 +41,8 @@ public interface CookieProcessor {
* are browser versions incompatible with the SameSite attribute. This is described by
* <a href="https://www.chromium.org/updates/same-site/incompatible-clients">the Chromium project</a>.
*
- * @param request The servlet request
* @param cookie The cookie for which the header will be generated
+ * @param request The servlet request
*
* @return The header value in a form that can be added directly to the response
*/
diff --git a/java/org/apache/tomcat/util/http/CookiesWithoutEquals.java b/java/org/apache/tomcat/util/http/CookiesWithoutEquals.java
index 1e228cc838..74a71552b0 100644
--- a/java/org/apache/tomcat/util/http/CookiesWithoutEquals.java
+++ b/java/org/apache/tomcat/util/http/CookiesWithoutEquals.java
@@ -38,7 +38,7 @@ public enum CookiesWithoutEquals {
* There is no VALUE option since the Servlet specification does not permit the creation of a Cookie with a name
* that is either null or the zero length string.
*
- * In RFC 2019, cookie name and value were defined as follows:
+ * In RFC 2109, cookie name and value were defined as follows:
* cookie = NAME "=" VALUE *(";" cookie-av)
* NAME = attr
* VALUE = value
@@ -68,7 +68,7 @@ public enum CookiesWithoutEquals {
* - both empty name and empty value are allowed but if both are empty the cookie will be ignored.
* @formatter:on
*
- * To see how RFC6265 arrived at his behaviour, see https://github.com/httpwg/http-extensions/issues/159
+ * To see how RFC6265 arrived at its behaviour, see https://github.com/httpwg/http-extensions/issues/159
*
* Historically, the users agents settled on using a name-value-pair without an equals sign to indicate a cookie
* with a value but no name. Tomcat did the opposite. That arose from addressing this bug:
diff --git a/java/org/apache/tomcat/util/http/MimeHeaders.java b/java/org/apache/tomcat/util/http/MimeHeaders.java
index 3a61c6a5b7..052c5dc517 100644
--- a/java/org/apache/tomcat/util/http/MimeHeaders.java
+++ b/java/org/apache/tomcat/util/http/MimeHeaders.java
@@ -253,8 +253,8 @@ public class MimeHeaders {
// -------------------- --------------------
/**
- * Returns an enumeration of strings representing the header field names. Field names may appear multiple times in
- * this enumeration, indicating that multiple fields with that name exist in this header.
+ * Returns an enumeration of strings representing the distinct header field names. Each distinct name appears once
+ * in this enumeration, even if multiple fields with that name exist in this header.
*
* @return the enumeration
*/
diff --git a/java/org/apache/tomcat/util/http/Parameters.java b/java/org/apache/tomcat/util/http/Parameters.java
index 984fd01b36..990079efac 100644
--- a/java/org/apache/tomcat/util/http/Parameters.java
+++ b/java/org/apache/tomcat/util/http/Parameters.java
@@ -145,7 +145,7 @@ public final class Parameters {
/*
* queryStringCharset cannot be recycled here as it needs to be set to Connector.getURICharset() which is not
* accessible from Parameters. queryStringCharset is therefore reset at the start of every request in
- * CoyoteAdpater.service().
+ * CoyoteAdapter.service().
*/
}
diff --git a/java/org/apache/tomcat/util/http/RequestUtil.java b/java/org/apache/tomcat/util/http/RequestUtil.java
index dea89dd9b2..8da10e3f98 100644
--- a/java/org/apache/tomcat/util/http/RequestUtil.java
+++ b/java/org/apache/tomcat/util/http/RequestUtil.java
@@ -171,8 +171,8 @@ public class RequestUtil {
}
- // Both scheme and host are case-insensitive usually
- // However, CORS same origin check must be case-sensitive (from the CORS specification)
+ // Both scheme and host are case-insensitive and the CORS same origin check (from the Fetch/CORS
+ // specification) compares them case-insensitively.
return origin.contentEquals(target);
}
@@ -189,7 +189,8 @@ public class RequestUtil {
*
* @return <code>true</code> if the origin was valid
*
- * @see <a href="http://tools.ietf.org/html/rfc952">RFC952</a>
+ * @see <a href="http://tools.ietf.org/html/rfc6454">RFC 6454</a>
+ * @see <a href="http://tools.ietf.org/html/rfc3986">RFC 3986</a>
*/
public static boolean isValidOrigin(String origin) {
// Checks for encoded characters. Helps prevent CRLF injection.
diff --git a/java/org/apache/tomcat/util/http/WebdavIfHeader.java b/java/org/apache/tomcat/util/http/WebdavIfHeader.java
index 220dcf9a72..2c918511e7 100644
--- a/java/org/apache/tomcat/util/http/WebdavIfHeader.java
+++ b/java/org/apache/tomcat/util/http/WebdavIfHeader.java
@@ -146,7 +146,7 @@ public class WebdavIfHeader {
}
/**
- * Return the String representation of the If header present on the given request or <code>null</code>.
+ * Return the String representation of the If header value or <code>null</code> if no If header is present.
*
* @return If header value as String or <code>null</code>.
*/
@@ -155,9 +155,9 @@ public class WebdavIfHeader {
}
/**
- * Returns true if an If header was present in the given request. False otherwise.
+ * Returns true if an If header is present. False otherwise.
*
- * @return true if an If header was present.
+ * @return true if an If header is present.
*/
public boolean hasValue() {
return ifHeader != null;
@@ -340,7 +340,7 @@ public class WebdavIfHeader {
}
/**
- * Parses an <em>IfList</em> in the <em>If</em> header. This method implements the <em>Tagged</em> production given
+ * Parses an <em>IfList</em> in the <em>If</em> header. This method implements the <em>IfList</em> production given
* in the class comment :
*
* <pre>
@@ -851,15 +851,15 @@ public class WebdavIfHeader {
private static final long serialVersionUID = 1L;
/**
- * Matches the token and etag for the given resource. If the resource is not mentioned in the header, a match is
- * assumed and <code>true</code> is returned in this case.
+ * Matches the token and etag for the given resource. If the resource is not mentioned in the header, a mismatch
+ * is assumed and <code>false</code> is returned in this case.
*
* @param resource The absolute URI of the resource for which to find a match.
* @param tokens The tokens to compare.
* @param etag The etag to compare.
*
- * @return <code>true</code> if either no entry exists for the resource or if the entry for the resource matches
- * the token and etag.
+ * @return <code>true</code> if the entry for the resource matches the token and etag, <code>false</code>
+ * otherwise (including when no entry exists for the resource).
*/
@Override
public boolean matches(String resource, List<String> tokens, String etag) {
diff --git a/java/org/apache/tomcat/util/http/fileupload/ThresholdingOutputStream.java b/java/org/apache/tomcat/util/http/fileupload/ThresholdingOutputStream.java
index f2ea6e938b..9d6794c25b 100644
--- a/java/org/apache/tomcat/util/http/fileupload/ThresholdingOutputStream.java
+++ b/java/org/apache/tomcat/util/http/fileupload/ThresholdingOutputStream.java
@@ -170,7 +170,7 @@ public abstract class ThresholdingOutputStream
* Determines whether or not the configured threshold has been exceeded for
* this output stream.
*
- * @return {@code true} if the threshold has been reached;
+ * @return {@code true} if the threshold has been exceeded;
* {@code false} otherwise.
*/
public boolean isThresholdExceeded()
diff --git a/java/org/apache/tomcat/util/http/fileupload/util/LimitedInputStream.java b/java/org/apache/tomcat/util/http/fileupload/util/LimitedInputStream.java
index add304c16a..70488a1177 100644
--- a/java/org/apache/tomcat/util/http/fileupload/util/LimitedInputStream.java
+++ b/java/org/apache/tomcat/util/http/fileupload/util/LimitedInputStream.java
@@ -21,8 +21,8 @@ import java.io.IOException;
import java.io.InputStream;
/**
- * An input stream, which limits its data size. This stream is
- * used, if the content length is unknown.
+ * An input stream, which limits its data size. This stream is used to enforce
+ * a configured maximum size on the underlying stream.
*/
public abstract class LimitedInputStream extends FilterInputStream implements Closeable {
@@ -111,8 +111,8 @@ public abstract class LimitedInputStream extends FilterInputStream implements Cl
* is available, the end of the stream is detected, or an exception
* is thrown.
* <p>
- * This method
- * simply performs {@code in.read()} and returns the result.
+ * This method performs {@code in.read()}, increments the internal byte
+ * counter and may raise the limit-exceeded error.
*
* @return the next byte of data, or {@code -1} if the end of the
* stream is reached.
@@ -135,8 +135,8 @@ public abstract class LimitedInputStream extends FilterInputStream implements Cl
* blocks until some input is available; otherwise, no
* bytes are read and {@code 0} is returned.
* <p>
- * This method simply performs {@code in.read(b, off, len)}
- * and returns the result.
+ * This method performs {@code in.read(b, off, len)}, increments the
+ * internal byte counter and may raise the limit-exceeded error.
*
* @param b the buffer into which the data is read.
* @param off The start offset in the destination array
diff --git a/java/org/apache/tomcat/util/http/fileupload/util/mime/MimeUtility.java b/java/org/apache/tomcat/util/http/fileupload/util/mime/MimeUtility.java
index 461b00b354..a311ead520 100644
--- a/java/org/apache/tomcat/util/http/fileupload/util/mime/MimeUtility.java
+++ b/java/org/apache/tomcat/util/http/fileupload/util/mime/MimeUtility.java
@@ -85,6 +85,7 @@ public final class MimeUtility {
*
* @return The decoded text string.
* @throws UnsupportedEncodingException if the detected encoding in the input text is not supported.
+ * @throws IllegalArgumentException if a malformed base64 encoded-word is encountered.
*/
public static String decodeText(final String text) throws UnsupportedEncodingException {
// if the text contains any encoded tokens, those tokens will be marked with "=?". If the
@@ -139,7 +140,7 @@ public final class MimeUtility {
// is the token encoded? decode the word
if (word.startsWith(ENCODED_TOKEN_MARKER)) {
try {
- // if this gives a parsing failure, treat it like a non-encoded word.
+ // if this gives a ParseException, treat it like a non-encoded word.
final String decodedWord = decodeWord(word);
// are any whitespace characters significant? Append 'em if we've got 'em.
@@ -151,7 +152,7 @@ public final class MimeUtility {
previousTokenEncoded = true;
// and add this to the text.
decodedText.append(decodedWord);
- // we continue parsing from here...we allow parsing errors to fall through
+ // we continue parsing from here...we allow ParseExceptions to fall through
// and get handled as normal text.
continue;
diff --git a/java/org/apache/tomcat/util/http/parser/AcceptLanguage.java b/java/org/apache/tomcat/util/http/parser/AcceptLanguage.java
index 42d0c9727a..0f2783f61a 100644
--- a/java/org/apache/tomcat/util/http/parser/AcceptLanguage.java
+++ b/java/org/apache/tomcat/util/http/parser/AcceptLanguage.java
@@ -64,7 +64,7 @@ public class AcceptLanguage {
* Parses an Accept-Language header value.
*
* @param input The StringReader containing the header value
- * @return A list of AcceptLanguage entries sorted by quality
+ * @return A list of AcceptLanguage entries in the order they appear in the header
* @throws IOException If an I/O error occurs while reading the input
*/
public static List<AcceptLanguage> parse(StringReader input) throws IOException {
diff --git a/java/org/apache/tomcat/util/http/parser/Cookie.java b/java/org/apache/tomcat/util/http/parser/Cookie.java
index 7dcf532a87..f0564a4127 100644
--- a/java/org/apache/tomcat/util/http/parser/Cookie.java
+++ b/java/org/apache/tomcat/util/http/parser/Cookie.java
@@ -60,7 +60,7 @@ public class Cookie {
private static final byte COMMA_BYTE = (byte) 0x2C;
private static final byte SEMICOLON_BYTE = (byte) 0x3B;
private static final byte EQUALS_BYTE = (byte) 0x3D;
- private static final byte SLASH_BYTE = (byte) 0x5C;
+ private static final byte BACKSLASH_BYTE = (byte) 0x5C;
private static final byte DEL_BYTE = (byte) 0x7F;
@@ -69,7 +69,7 @@ public class Cookie {
// %x80 to %xFF (UTF-8)
for (int i = 0; i < 256; i++) {
isCookieOctet[i] = !(i < 0x21 || i == QUOTE_BYTE || i == COMMA_BYTE || i == SEMICOLON_BYTE ||
- i == SLASH_BYTE || i == DEL_BYTE);
+ i == BACKSLASH_BYTE || i == DEL_BYTE);
}
for (int i = 0; i < 256; i++) {
isText[i] = !(i < TAB_BYTE || (i > TAB_BYTE && i < SPACE_BYTE) || i == DEL_BYTE);
diff --git a/java/org/apache/tomcat/util/http/parser/HttpHeaderParser.java b/java/org/apache/tomcat/util/http/parser/HttpHeaderParser.java
index b52bb38bbf..2e7be33c3e 100644
--- a/java/org/apache/tomcat/util/http/parser/HttpHeaderParser.java
+++ b/java/org/apache/tomcat/util/http/parser/HttpHeaderParser.java
@@ -339,8 +339,8 @@ public class HttpHeaderParser {
/**
* Reading a header name. All characters of header are HTTP_TOKEN_CHAR. Header name is followed by ':'. No
* whitespace is allowed.<br>
- * Any non-HTTP_TOKEN_CHAR (this includes any whitespace) encountered before ':' will result in the whole line
- * being ignored.
+ * Any non-HTTP_TOKEN_CHAR (this includes any whitespace) encountered before ':' will cause an
+ * {@code IllegalArgumentException} to be thrown, resulting in the whole request being rejected.
*/
HEADER_NAME,
/**
diff --git a/java/org/apache/tomcat/util/http/parser/MediaType.java b/java/org/apache/tomcat/util/http/parser/MediaType.java
index 45845e3452..d0a54682af 100644
--- a/java/org/apache/tomcat/util/http/parser/MediaType.java
+++ b/java/org/apache/tomcat/util/http/parser/MediaType.java
@@ -173,7 +173,9 @@ public class MediaType {
*
* @param input a reader over the header text
*
- * @return a MediaType parsed from the input, or null if not valid
+ * @return a MediaType parsed from the input, or null if the required type or subtype is missing. Some
+ * syntactically invalid parameter values (e.g. a dangling {@code ;}) are accepted and produce a
+ * non-null result.
*
* @throws IOException if there was a problem reading the input
*/
diff --git a/java/org/apache/tomcat/util/http/parser/Priority.java b/java/org/apache/tomcat/util/http/parser/Priority.java
index c1d8dc419f..de42d60b90 100644
--- a/java/org/apache/tomcat/util/http/parser/Priority.java
+++ b/java/org/apache/tomcat/util/http/parser/Priority.java
@@ -88,7 +88,7 @@ public class Priority {
/**
- * Parsers an HTTP header as a Priority header as defined by RFC 9218.
+ * Parses an HTTP header as a Priority header as defined by RFC 9218.
*
* @param input The header to parse
*
diff --git a/java/org/apache/tomcat/util/http/parser/Ranges.java b/java/org/apache/tomcat/util/http/parser/Ranges.java
index 6cd73fab31..9685c28964 100644
--- a/java/org/apache/tomcat/util/http/parser/Ranges.java
+++ b/java/org/apache/tomcat/util/http/parser/Ranges.java
@@ -81,7 +81,7 @@ public class Ranges {
/**
* Creates a new range entry.
*
- * @param start the start position of the range
+ * @param start the start position of the range, or -1 if absent (suffix range)
* @param end the end position of the range, or -1 if absent
*/
public Entry(long start, long end) {
diff --git a/java/org/apache/tomcat/util/http/parser/TE.java b/java/org/apache/tomcat/util/http/parser/TE.java
index eb5ba9bf99..5e027994c6 100644
--- a/java/org/apache/tomcat/util/http/parser/TE.java
+++ b/java/org/apache/tomcat/util/http/parser/TE.java
@@ -24,7 +24,7 @@ import java.util.List;
import java.util.Map;
/**
- * Represents a Transfer-Encoding value with optional parameters and quality factor.
+ * Represents a single transfer coding in a TE header value, with optional parameters and quality factor.
*/
public class TE {
@@ -85,7 +85,7 @@ public class TE {
/**
- * Parses a Transfer-Encoding header value into a list of TE instances.
+ * Parses a TE header value into a list of TE instances.
*
* @param input the input reader containing the header value
* @return the list of parsed TE values
diff --git a/java/org/apache/tomcat/util/json/JSONParser.java b/java/org/apache/tomcat/util/json/JSONParser.java
index cb9cf3500b..c21b0f67f9 100644
--- a/java/org/apache/tomcat/util/json/JSONParser.java
+++ b/java/org/apache/tomcat/util/json/JSONParser.java
@@ -20,8 +20,10 @@ package org.apache.tomcat.util.json;
/**
* Basic JSON parser generated by JavaCC. It consumes the input provided through the constructor when
- * {@code parseObject()}, {@code parseList()}, or {@code parse()} are called, and there is no way to directly reset the
- * state.
+ * {@code parseObject()}, {@code parseArray()}, or {@code parse()} are called. The parser state can be reset using one
+ * of the {@code ReInit} methods.
+ * <p>
+ * This class is stateful and not thread-safe.
*/
@SuppressWarnings("all") // Ignore warnings in generated code
public class JSONParser implements JSONParserConstants {
diff --git a/java/org/apache/tomcat/util/json/JSONParser.jjt b/java/org/apache/tomcat/util/json/JSONParser.jjt
index 38f9e0a0b7..08996d10ab 100644
--- a/java/org/apache/tomcat/util/json/JSONParser.jjt
+++ b/java/org/apache/tomcat/util/json/JSONParser.jjt
@@ -51,14 +51,14 @@ package org.apache.tomcat.util.json;
/**
* Basic JSON parser generated by JavaCC. It consumes the input provided through the constructor when
-* {@code parseObject()}, {@code parseList()}, or {@code parse()} are called, and there is no way to directly
-* reset the state.
+* {@code parseObject()}, {@code parseArray()}, or {@code parse()} are called. The parser state can be reset using one
+* of the {@code ReInit} methods.
+* <p>
+* This class is stateful and not thread-safe.
*/
@SuppressWarnings("all") // Ignore warnings in generated code
public class JSONParser {
- protected static final org.apache.tomcat.util.res.StringManager sm = org.apache.tomcat.util.res.StringManager.getManager(JSONParser.class);
-
private boolean nativeNumbers = false;
public JSONParser(String input) {
@@ -71,7 +71,7 @@ public class JSONParser {
public java.util.LinkedHashMap<String, Object> parseObject() throws ParseException {
java.util.LinkedHashMap<String, Object> toReturn = object();
if (!ensureEOF()) {
- throw new IllegalStateException(sm.getString("parser.expectedEOF"));
+ throw new IllegalStateException("Expected EOF, but still had content to parse");
}
return toReturn;
}
@@ -82,7 +82,7 @@ public class JSONParser {
public java.util.ArrayList<Object> parseArray() throws ParseException {
java.util.ArrayList<Object> toReturn = list();
if (!ensureEOF()) {
- throw new IllegalStateException(sm.getString("parser.expectedEOF"));
+ throw new IllegalStateException("Expected EOF, but still had content to parse");
}
return toReturn;
}
@@ -93,7 +93,7 @@ public class JSONParser {
public Object parse() throws ParseException {
Object toReturn = anything();
if (!ensureEOF()) {
- throw new IllegalStateException(sm.getString("parser.expectedEOF"));
+ throw new IllegalStateException("Expected EOF, but still had content to parse");
}
return toReturn;
}
diff --git a/java/org/apache/tomcat/util/log/SystemLogHandler.java b/java/org/apache/tomcat/util/log/SystemLogHandler.java
index 6d7d9ea73e..41c8654a69 100644
--- a/java/org/apache/tomcat/util/log/SystemLogHandler.java
+++ b/java/org/apache/tomcat/util/log/SystemLogHandler.java
@@ -35,7 +35,7 @@ public class SystemLogHandler extends PrintStream {
/**
- * Construct the handler to capture the output of the given steam.
+ * Construct the handler to capture the output of the given stream.
*
* @param wrapped The stream to capture
*/
diff --git a/java/org/apache/tomcat/util/log/UserDataHelper.java b/java/org/apache/tomcat/util/log/UserDataHelper.java
index 07f48d4f96..ad348bdc95 100644
--- a/java/org/apache/tomcat/util/log/UserDataHelper.java
+++ b/java/org/apache/tomcat/util/log/UserDataHelper.java
@@ -23,10 +23,11 @@ import org.apache.juli.logging.Log;
* invalid input data logged to assist with debugging whereas in production it is likely to be desirable not to log
* anything for invalid data. The following settings may be used:
* <ul>
- * <li>NOTHING: Log nothing.</li>
+ * <li>NONE: Log nothing.</li>
* <li>DEBUG_ALL: Log all problems at DEBUG log level.</li>
- * <li>INFO_THEN_DEBUG: Log first problem at INFO log level and any further issues in the following TBD (configurable)
- * seconds at DEBUG level</li>
+ * <li>INFO_THEN_DEBUG: Log first problem at INFO log level and any further issues in the following configurable
+ * suppression time (the <code>org.apache.juli.logging.UserDataHelper.SUPPRESSION_TIME</code> system property, in
+ * seconds) at DEBUG level</li>
* <li>INFO_ALL: Log all problems at INFO log level.</li>
* </ul>
* By default, INFO_THEN_DEBUG is used with a suppression time of 24 hours.
diff --git a/java/org/apache/tomcat/util/modeler/BaseModelMBean.java b/java/org/apache/tomcat/util/modeler/BaseModelMBean.java
index 30c5f0ff53..ad5566cb6e 100644
--- a/java/org/apache/tomcat/util/modeler/BaseModelMBean.java
+++ b/java/org/apache/tomcat/util/modeler/BaseModelMBean.java
@@ -56,7 +56,7 @@ import org.apache.tomcat.util.res.StringManager;
* uses, but now it is required.
* - some of the gratuitous flexibility removed - instead this is more predictive and
* strict with the use cases.
- * - all Method and metadata is stored in ManagedBean. BaseModelBMean and ManagedBean act
+ * - all Method and metadata is stored in ManagedBean. BaseModelMBean and ManagedBean act
* like Object and Class.
* - setModelMBean is no longer called on resources ( not used in tomcat )
* - no caching of Methods for now - operations and setters are not called repeatedly in most
@@ -64,9 +64,6 @@ import org.apache.tomcat.util.res.StringManager;
* are, the overhead of getting the method should be small compared with other JMX costs ( RMI, etc ).
* We can add getter cache if needed.
* - removed unused constructor, fields
- *
- * TODO:
- * - clean up catalina.mbeans, stop using weird inheritance
*/
/**
@@ -88,6 +85,8 @@ import org.apache.tomcat.util.res.StringManager;
* <ul>
* <li>One of the Java primitive types (boolean, byte, char, double, float, integer, long, short). Corresponding value
* will be wrapped in the appropriate wrapper class automatically.</li>
+ * <li>Any other Bean-compatible class, such as <code>String</code>, <code>String[]</code>, <code>Object[]</code>,
+ * <code>ObjectName</code>, <code>BigDecimal</code>, <code>BigInteger</code> or <code>java.io.File</code>.</li>
* <li>Operations that return no value should declare a return type of <code>void</code>.</li>
* </ul>
* <li>Attribute caching is not supported</li>
@@ -466,7 +465,8 @@ public class BaseModelMBean implements DynamicMBean, MBeanRegistration, ModelMBe
*
* @param resource The resource object to be managed
* @param type The type of reference for the managed resource ("ObjectReference", "Handle", "IOR", "EJBHandle",
- * or "RMIReference")
+ * or "RMIReference"). This parameter is not used; the resource type is derived from the
+ * resource object.
*
* @exception InstanceNotFoundException if the managed resource object cannot be found
* @exception MBeanException if the initializer of the object throws an exception
diff --git a/java/org/apache/tomcat/util/modeler/ManagedBean.java b/java/org/apache/tomcat/util/modeler/ManagedBean.java
index a5d555b56a..7236e5d522 100644
--- a/java/org/apache/tomcat/util/modeler/ManagedBean.java
+++ b/java/org/apache/tomcat/util/modeler/ManagedBean.java
@@ -133,7 +133,7 @@ public class ManagedBean implements java.io.Serializable {
/**
* The fully qualified name of the Java class of the MBean described by this descriptor. If not specified, the
- * standard JMX class (<code>javax.management.modelmbean.RequiredModeLMBean</code>) will be utilized.
+ * default class (<code>org.apache.tomcat.util.modeler.BaseModelMBean</code>) will be utilized.
*
* @return the class name
*/
diff --git a/java/org/apache/tomcat/util/modeler/NotificationInfo.java b/java/org/apache/tomcat/util/modeler/NotificationInfo.java
index 8855b70a35..9bf5c07b77 100644
--- a/java/org/apache/tomcat/util/modeler/NotificationInfo.java
+++ b/java/org/apache/tomcat/util/modeler/NotificationInfo.java
@@ -115,8 +115,8 @@ public class NotificationInfo extends FeatureInfo {
/**
- * Create and return a <code>ModelMBeanNotificationInfo</code> object that corresponds to the attribute described by
- * this instance.
+ * Create and return a <code>ModelMBeanNotificationInfo</code> object that corresponds to the notification
+ * described by this instance.
*
* @return the notification info
*/
diff --git a/java/org/apache/tomcat/util/modeler/OperationInfo.java b/java/org/apache/tomcat/util/modeler/OperationInfo.java
index 24a973866e..36c7d4412e 100644
--- a/java/org/apache/tomcat/util/modeler/OperationInfo.java
+++ b/java/org/apache/tomcat/util/modeler/OperationInfo.java
@@ -164,7 +164,7 @@ public class OperationInfo extends FeatureInfo {
/**
- * Create and return a <code>ModelMBeanOperationInfo</code> object that corresponds to the attribute described by
+ * Create and return a <code>ModelMBeanOperationInfo</code> object that corresponds to the operation described by
* this instance.
*
* @return the operation info
diff --git a/java/org/apache/tomcat/util/modeler/Registry.java b/java/org/apache/tomcat/util/modeler/Registry.java
index 7d9799dcdc..5a08c7a10b 100644
--- a/java/org/apache/tomcat/util/modeler/Registry.java
+++ b/java/org/apache/tomcat/util/modeler/Registry.java
@@ -44,7 +44,7 @@ import org.apache.tomcat.util.res.StringManager;
/**
* Registry for modeler MBeans. This is the main entry point into modeler. It provides methods to create and manipulate
- * model mbeans and simplify their use. This class is itself a mbean.
+ * model mbeans and simplify their use.
*/
public class Registry implements RegistryMBean, MBeanRegistration {
@@ -109,7 +109,7 @@ public class Registry implements RegistryMBean, MBeanRegistration {
* @param key Unused
* @param guard Prevent access to the registry by untrusted components
*
- * @return the registry
+ * @return the registry, or {@code null} if the guard object does not allow access to the registry
*
* @since 1.1
*/
@@ -162,7 +162,7 @@ public class Registry implements RegistryMBean, MBeanRegistration {
// -------------------- Generic methods --------------------
/**
- * Lifecycle method - clean up the registry metadata. Called from resetMetadata().
+ * Lifecycle method - clean up the registry metadata.
*
* @since 1.1
*/
@@ -176,7 +176,7 @@ public class Registry implements RegistryMBean, MBeanRegistration {
/**
* Register a bean by creating a modeler mbean and adding it to the MBeanServer. If metadata is not loaded, we'll
- * look up and read a file named "mbeans-descriptors.ser" or "mbeans-descriptors.xml" in the same package or parent.
+ * look up and read a file named "mbeans-descriptors.xml" in the same package or parent.
* If the bean is an instance of DynamicMBean. its metadata will be converted to a model mbean, and we'll wrap it so
* modeler services are supported. If the metadata is still not found, introspection will be used to extract it
* automatically. If a mbean is already registered under this name, it'll be first unregistered. If the component
@@ -659,7 +659,7 @@ public class Registry implements RegistryMBean, MBeanRegistration {
/**
- * Lookup the component descriptor in the package and in the parent packages.
+ * Lookup the component descriptor in the given package.
*
* @param packageName The package name
* @param classLoader The class loader
diff --git a/java/org/apache/tomcat/util/modeler/RegistryMBean.java b/java/org/apache/tomcat/util/modeler/RegistryMBean.java
index 1d81593404..3b75b65f99 100644
--- a/java/org/apache/tomcat/util/modeler/RegistryMBean.java
+++ b/java/org/apache/tomcat/util/modeler/RegistryMBean.java
@@ -23,8 +23,8 @@ import javax.management.ObjectName;
/**
* Interface for modeler MBeans. This is the main entry point into modeler. It provides methods to create and manipulate
- * model mbeans and simplify their use. Starting with version 1.1, this is no longer a singleton and the static methods
- * are strongly deprecated. In a container environment we can expect different applications to use different registries.
+ * model mbeans and simplify their use. Starting with version 1.1, this is no longer a singleton. In a container
+ * environment we can expect different applications to use different registries.
*/
public interface RegistryMBean {
@@ -41,7 +41,7 @@ public interface RegistryMBean {
/**
* Register a bean by creating a modeler mbean and adding it to the MBeanServer. If metadata is not loaded, we'll
- * look up and read a file named "mbeans-descriptors.ser" or "mbeans-descriptors.xml" in the same package or parent.
+ * look up and read a file named "mbeans-descriptors.xml" in the same package or parent.
* If the bean is an instance of DynamicMBean. it's metadata will be converted to a model mbean, and we'll wrap it -
* so modeler services will be supported If the metadata is still not found, introspection will be used to extract
* it automatically. If a mbean is already registered under this name, it'll be first unregistered. If the component
@@ -84,7 +84,7 @@ public interface RegistryMBean {
/**
* Reset all metadata cached by this registry. Should be called to support reloading. Existing mbeans will not be
- * affected or modified. It will be called automatically if the Registry is unregistered.
+ * affected or modified.
*
* @since 1.1
*/
diff --git a/java/org/apache/tomcat/util/modeler/modules/MbeansDescriptorsIntrospectionSource.java b/java/org/apache/tomcat/util/modeler/modules/MbeansDescriptorsIntrospectionSource.java
index d61c239b96..237e97b0d3 100644
--- a/java/org/apache/tomcat/util/modeler/modules/MbeansDescriptorsIntrospectionSource.java
+++ b/java/org/apache/tomcat/util/modeler/modules/MbeansDescriptorsIntrospectionSource.java
@@ -95,9 +95,7 @@ public class MbeansDescriptorsIntrospectionSource extends ModelerSource {
}
/**
- * Execute the descriptor loading.
- *
- * @throws Exception if an error occurs
+ * Execute the descriptor loading. Errors are logged and not propagated.
*/
public void execute() throws Exception {
if (registry == null) {
@@ -270,9 +268,6 @@ public class MbeansDescriptorsIntrospectionSource extends ModelerSource {
}
/**
- * XXX Find if the 'className' is the name of the MBean or the real class ( I suppose first ) XXX Read (optional)
- * descriptions from a .properties, generated from source XXX Deal with constructors
- *
* @param registry The Bean registry (not used)
* @param domain The bean domain (not used)
* @param realClass The class to analyze
diff --git a/java/org/apache/tomcat/util/modeler/modules/ModelerSource.java b/java/org/apache/tomcat/util/modeler/modules/ModelerSource.java
index b26bdc0ad0..d4645bd95d 100644
--- a/java/org/apache/tomcat/util/modeler/modules/ModelerSource.java
+++ b/java/org/apache/tomcat/util/modeler/modules/ModelerSource.java
@@ -34,7 +34,7 @@ public abstract class ModelerSource {
}
/**
- * The string manager for this class.
+ * The string manager for the package that contains {@link Registry}.
*/
protected static final StringManager sm = StringManager.getManager(Registry.class);
/**
diff --git a/java/org/apache/tomcat/util/net/NioEndpoint.java b/java/org/apache/tomcat/util/net/NioEndpoint.java
index 21b0cadbbb..9200f44f94 100644
--- a/java/org/apache/tomcat/util/net/NioEndpoint.java
+++ b/java/org/apache/tomcat/util/net/NioEndpoint.java
@@ -344,8 +344,8 @@ public class NioEndpoint extends AbstractNetworkChannelEndpoint<NioChannel,Socke
/**
* Number of keep-alive sockets.
*
- * @return The number of sockets currently in the keep-alive state waiting for the next request to be received on
- * the socket
+ * @return The number of sockets currently registered with the poller (i.e. all active sockets, including the
+ * keep-alive sockets waiting for the next request to be received on the socket)
*/
public int getKeepAliveCount() {
if (poller == null) {
@@ -971,8 +971,8 @@ public class NioEndpoint extends AbstractNetworkChannelEndpoint<NioChannel,Socke
/**
* Add specified socket and associated pool to the poller. The socket will be added to a temporary array, and
- * polled first after a maximum amount of time equal to pollTime (in most cases, latency will be much lower,
- * however).
+ * polled first after a maximum amount of time equal to the <code>selectorTimeout</code> (in most cases, latency
+ * will be much lower, however).
*
* @param socketWrapper to add to the poller
* @param interestOps Operations for which to register this socket with the Poller
diff --git a/java/org/apache/tomcat/util/net/SecureNioChannel.java b/java/org/apache/tomcat/util/net/SecureNioChannel.java
index 25ee13103a..8006e363dd 100644
--- a/java/org/apache/tomcat/util/net/SecureNioChannel.java
+++ b/java/org/apache/tomcat/util/net/SecureNioChannel.java
@@ -160,8 +160,9 @@ public class SecureNioChannel extends NioChannel {
* @return 0 if handshake is complete, -1 if an error (other than an IOException) occurred, otherwise it returns a
* SelectionKey interestOps value
*
- * @throws IOException If an I/O error occurs during the handshake or if the handshake fails during wrapping or
- * unwrapping
+ * @throws IOException If an I/O error occurs during the handshake or if the handshake fails during
+ * wrapping or unwrapping
+ * @throws IllegalStateException If an invalid handshake status is encountered during the handshake
*/
@Override
public int handshake(boolean read, boolean write) throws IOException {
@@ -556,7 +557,6 @@ public class SecureNioChannel extends NioChannel {
* </pre>
*
* @throws IOException if an I/O error occurs
- * @throws IOException if there is data on the outgoing network buffer, and we are unable to flush it
*/
@Override
public void close() throws IOException {
diff --git a/java/org/apache/tomcat/util/net/SendfileDataBase.java b/java/org/apache/tomcat/util/net/SendfileDataBase.java
index 8a31437ba0..bc4a42c153 100644
--- a/java/org/apache/tomcat/util/net/SendfileDataBase.java
+++ b/java/org/apache/tomcat/util/net/SendfileDataBase.java
@@ -42,7 +42,7 @@ public abstract class SendfileDataBase {
/**
* The number of bytes remaining to be written from the file (from the current {@link #pos}). This is initialised to
- * the end point - the start point and then updated as the file is written.
+ * the value provided by the caller and then updated as the file is written.
*/
public long length;
diff --git a/java/org/apache/tomcat/util/net/SocketProperties.java b/java/org/apache/tomcat/util/net/SocketProperties.java
index b70a113e7b..66d76e1754 100644
--- a/java/org/apache/tomcat/util/net/SocketProperties.java
+++ b/java/org/apache/tomcat/util/net/SocketProperties.java
@@ -103,13 +103,14 @@ public class SocketProperties {
* <p>
* -1 means unlimited<br>
* 0 means no cache<br>
- * Default value is based on the max memory reported by the JVM, if less than 1GB, then 0, else the value divided by
- * 32. This value will then be used to compute bufferPool if its value is -2
+ * Default value is based on the max memory reported by the JVM, if greater than
+ * <code>Integer.MAX_VALUE</code> (about 2 GB), then the value divided by 32, else 0. This value will then be used
+ * to compute bufferPool if its value is -2
*/
protected int bufferPoolSize = -2;
/**
- * TCP_NO_DELAY option. JVM default used if not set.
+ * TCP_NO_DELAY option. Default is <code>true</code>.
*/
protected Boolean tcpNoDelay = Boolean.TRUE;
@@ -455,8 +456,8 @@ public class SocketProperties {
}
/**
- * Returns the direct buffer pool size.
- * @return the direct buffer pool size
+ * Returns the buffer pool size.
+ * @return the buffer pool size
*/
public int getDirectBufferPool() {
return bufferPool;
diff --git a/java/org/apache/tomcat/util/net/SocketWrapperBase.java b/java/org/apache/tomcat/util/net/SocketWrapperBase.java
index 98785b8974..0cef69262a 100644
--- a/java/org/apache/tomcat/util/net/SocketWrapperBase.java
+++ b/java/org/apache/tomcat/util/net/SocketWrapperBase.java
@@ -767,8 +767,8 @@ public abstract class SocketWrapperBase<E> {
* Writes the provided data to the socket write buffer. If the socket write buffer fills during the write, the
* content of the socket write buffer is written to the network using a blocking write. Once that blocking write is
* complete, this method starts to fill the socket write buffer again. Depending on the size of the data to write,
- * there may be multiple writes to the network. On completion of this method there will always be space remaining in
- * the socket write buffer.
+ * there may be multiple writes to the network. On completion of this method the socket write buffer may contain
+ * data that still needs to be written to the socket.
*
* @param buf The byte array containing the data to be written
* @param off The offset within the byte array of the data to be written
@@ -796,8 +796,8 @@ public abstract class SocketWrapperBase<E> {
* Writes the provided data to the socket write buffer. If the socket write buffer fills during the write, the
* content of the socket write buffer is written to the network using a blocking write. Once that blocking write is
* complete, this method starts to fill the socket write buffer again. Depending on the size of the data to write,
- * there may be multiple writes to the network. On completion of this method there will always be space remaining in
- * the socket write buffer.
+ * there may be multiple writes to the network. On completion of this method the socket write buffer may contain
+ * data that still needs to be written to the socket.
*
* @param from The ByteBuffer containing the data to be written
*
@@ -957,7 +957,7 @@ public abstract class SocketWrapperBase<E> {
/**
- * Write the contents of the socketWriteBuffer to the socket. For blocking writes either then entire contents of the
+ * Write the contents of the socketWriteBuffer to the socket. For blocking writes either the entire contents of the
* buffer will be written or an IOException will be thrown. Partial blocking writes will not occur.
*
* @param block Should the write be blocking or not?
@@ -971,7 +971,7 @@ public abstract class SocketWrapperBase<E> {
/**
- * Write the contents of the ByteBuffer to the socket. For blocking writes either then entire contents of the buffer
+ * Write the contents of the ByteBuffer to the socket. For blocking writes either the entire contents of the buffer
* will be written or an IOException will be thrown. Partial blocking writes will not occur.
*
* @param block Should the write be blocking or not?
diff --git a/java/org/apache/tomcat/util/net/jsse/PEMFile.java b/java/org/apache/tomcat/util/net/jsse/PEMFile.java
index be8c690f42..ec45a7b34c 100644
--- a/java/org/apache/tomcat/util/net/jsse/PEMFile.java
+++ b/java/org/apache/tomcat/util/net/jsse/PEMFile.java
@@ -62,7 +62,8 @@ import org.ietf.jgss.GSSException;
import org.ietf.jgss.Oid;
/**
- * RFC 1421 PEM file containing X509 certificates or private keys.
+ * RFC 7468 PEM file containing X509 certificates or private keys, including the OpenSSL specific DEK-Info and PKCS #8
+ * PBES2 formats for encrypted private keys.
*/
public class PEMFile {
@@ -188,7 +189,8 @@ public class PEMFile {
* Construct a PEMFile from the given file with the password read from a separate file.
*
* @param filename The path to the PEM file
- * @param password The password to decrypt any encrypted private key
+ * @param password The password to decrypt any encrypted private key (ignored if
+ * <code>passwordFilename</code> is non-null)
* @param passwordFilename The path to the file containing the password
* @param keyAlgorithm The key algorithm, or null to auto-detect
*
@@ -425,7 +427,7 @@ public class PEMFile {
* OID - PKCS #5 PBES2 KDF OID - must be PBKDF2
* SEQ 5 - PKCS #5 PBKDF2-params
* OCTET STRING - PKCS #5 PBKDF2 salt
- * INT - PKCS #5 PBKDF2 interationCount
+ * INT - PKCS #5 PBKDF2 iterationCount
* INT - PKCS #5 PBKDF2 key length OPTIONAL
* SEQ 6 - PKCS #5 PBKDF2 PRF defaults to HmacSHA1 if not present
* OID - PKCS #5 PBKDF2 PRF OID
diff --git a/java/org/apache/tomcat/util/net/openssl/OpenSSLEngine.java b/java/org/apache/tomcat/util/net/openssl/OpenSSLEngine.java
index 80d8243cfa..40b5a914bd 100644
--- a/java/org/apache/tomcat/util/net/openssl/OpenSSLEngine.java
+++ b/java/org/apache/tomcat/util/net/openssl/OpenSSLEngine.java
@@ -122,7 +122,6 @@ public final class OpenSSLEngine extends SSLEngine implements SSLUtil.ProtocolIn
private static final int MAX_COMPRESSED_LENGTH = MAX_PLAINTEXT_LENGTH + 1024;
private static final int MAX_CIPHERTEXT_LENGTH = MAX_COMPRESSED_LENGTH + 1024;
- // Protocols
static final int VERIFY_DEPTH = 10;
// Header (5) + Data (2^14) + Compression (1024) + Encryption (1024) + MAC (20) + Padding (256)
diff --git a/java/org/apache/tomcat/util/net/openssl/ciphers/Cipher.java b/java/org/apache/tomcat/util/net/openssl/ciphers/Cipher.java
index 42add3b912..e1863e57ac 100644
--- a/java/org/apache/tomcat/util/net/openssl/ciphers/Cipher.java
+++ b/java/org/apache/tomcat/util/net/openssl/ciphers/Cipher.java
@@ -25,7 +25,7 @@ import java.util.Map;
import java.util.Set;
/**
- * All the standard cipher suites for SSL/TSL.
+ * All the standard cipher suites for SSL/TLS.
*
* @see <a href="https://github.com/openssl/openssl/blob/master/ssl/s3_lib.c" >OpenSSL cipher definitions</a>
* @see <a href="http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4" >The cipher suite
@@ -2697,7 +2697,7 @@ public enum Cipher {
// Cipher 0x00FF TLS_EMPTY_RENEGOTIATION_INFO_SCSV
- // TLS 1.3 ciphers (draft - v26)
+ // TLS 1.3 ciphers (RFC 8446)
/** Cipher 1301 */
TLS_AES_128_GCM_SHA256(
0x1301,
@@ -2790,8 +2790,7 @@ public enum Cipher {
* No other ciphers defined until 0xC001 below
*/
- /* ECC cipher suites from draft-ietf-tls-ecc-01.txt (
- Mar 15, 2001) */
+ /* ECC cipher suites (RFC 4492) */
/** Cipher C001 */
TLS_ECDH_ECDSA_WITH_NULL_SHA(
0xC001,
@@ -4716,7 +4715,7 @@ public enum Cipher {
null,
null
),
- /** Draft: https://tools.ietf.org/html/draft-ietf-tls-chacha20-poly1305-04 */
+ /** ChaCha20-Poly1305 ciphers (RFC 7905). */
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256(
0xCCA8,
"ECDHE-RSA-CHACHA20-POLY1305",
diff --git a/java/org/apache/tomcat/util/net/openssl/ciphers/Encryption.java b/java/org/apache/tomcat/util/net/openssl/ciphers/Encryption.java
index bc877e6e9c..43e1fe4efe 100644
--- a/java/org/apache/tomcat/util/net/openssl/ciphers/Encryption.java
+++ b/java/org/apache/tomcat/util/net/openssl/ciphers/Encryption.java
@@ -52,7 +52,7 @@ public enum Encryption {
DES,
/** IDEA encryption. */
IDEA,
- /** GOST 28147-89 with_CNT keyed hash. */
+ /** GOST 28147-89 encryption with CNT keyed hash. */
eGOST2814789CNT,
/** SEED encryption. */
SEED,
diff --git a/java/org/apache/tomcat/util/net/openssl/ciphers/KeyExchange.java b/java/org/apache/tomcat/util/net/openssl/ciphers/KeyExchange.java
index f46c907612..cb04dd895b 100644
--- a/java/org/apache/tomcat/util/net/openssl/ciphers/KeyExchange.java
+++ b/java/org/apache/tomcat/util/net/openssl/ciphers/KeyExchange.java
@@ -41,7 +41,7 @@ public enum KeyExchange {
*/
EDH,
/**
- * Pre-shared key (SSK_kPSK).
+ * Pre-shared key (SSL_kPSK).
*/
PSK,
/**
diff --git a/java/org/apache/tomcat/util/net/openssl/ciphers/OpenSSLCipherConfigurationParser.java b/java/org/apache/tomcat/util/net/openssl/ciphers/OpenSSLCipherConfigurationParser.java
index 1efc8bd6c5..c740394bf9 100644
--- a/java/org/apache/tomcat/util/net/openssl/ciphers/OpenSSLCipherConfigurationParser.java
+++ b/java/org/apache/tomcat/util/net/openssl/ciphers/OpenSSLCipherConfigurationParser.java
@@ -86,7 +86,7 @@ public class OpenSSLCipherConfigurationParser {
*/
private static final String eNULL = "eNULL";
/**
- * The cipher suites offering no authentication. This is currently the anonymous DH algorithms. T These cipher
+ * The cipher suites offering no authentication. This is currently the anonymous DH algorithms. These cipher
* suites are vulnerable to a 'man in the middle' attack and so their use is normally discouraged.
*/
private static final String aNULL = "aNULL";
@@ -861,8 +861,8 @@ public class OpenSSLCipherConfigurationParser {
*
* @param opensslCipherName The OpenSSL name for a cipher
*
- * @return The JSSE name for the specified OpenSSL cipher. If none is known, the IANA standard name will be returned
- * instead
+ * @return The first JSSE name for the specified OpenSSL cipher, or {@code null} if the name is not a known,
+ * unambiguous OpenSSL cipher name
*/
public static String openSSLToJsse(String opensslCipherName) {
if (!initialized) {
diff --git a/java/org/apache/tomcat/util/net/openssl/panama/OpenSSLEngine.java b/java/org/apache/tomcat/util/net/openssl/panama/OpenSSLEngine.java
index dbb42e1b53..6d747108f5 100644
--- a/java/org/apache/tomcat/util/net/openssl/panama/OpenSSLEngine.java
+++ b/java/org/apache/tomcat/util/net/openssl/panama/OpenSSLEngine.java
@@ -181,7 +181,7 @@ public final class OpenSSLEngine extends SSLEngine implements SSLUtil.ProtocolIn
* @param certificateVerificationOptionalNoCA Skip CA verification in optional mode
* @param noOcspCheck Enable OCSP if true
* @param ocspSoftFail Allow OCSP checks to pass if the responder can't be contacted
- * @param ocspTimeout Timout in ms to use for OCSP requests
+ * @param ocspTimeout Timeout in ms to use for OCSP requests
* @param ocspVerifyFlags Verification flags for OCSP
*/
OpenSSLEngine(Cleaner cleaner, MemorySegment sslCtx, String fallbackApplicationProtocol, boolean clientMode,
diff --git a/java/org/apache/tomcat/util/openssl/openssl_h_Macros.java b/java/org/apache/tomcat/util/openssl/openssl_h_Macros.java
index 5d86f7a54c..3bc9129ff8 100644
--- a/java/org/apache/tomcat/util/openssl/openssl_h_Macros.java
+++ b/java/org/apache/tomcat/util/openssl/openssl_h_Macros.java
@@ -72,7 +72,7 @@ public class openssl_h_Macros {
* }
*
* @param sslCtx the SSL context
- * @param version the maximum version
+ * @param version the minimum version
*
* @return > 0 if successful
*/
@@ -453,8 +453,8 @@ public class openssl_h_Macros {
/**
* Set list of groups in preference order.
* {@snippet lang = c :
- * # define SSL_set1_groups_list(s, str) \
- * SSL_ctrl(s,SSL_CTRL_SET_GROUPS_LIST,0,(char *)(str))
+ * # define SSL_CTX_set1_groups_list(s, str) \
+ * SSL_CTX_ctrl(s,SSL_CTRL_SET_GROUPS_LIST,0,(char *)(str))
* }
*
* @param sslCtx the SSL context
diff --git a/java/org/apache/tomcat/util/res/StringManager.java b/java/org/apache/tomcat/util/res/StringManager.java
index a904c58660..a893d629c2 100644
--- a/java/org/apache/tomcat/util/res/StringManager.java
+++ b/java/org/apache/tomcat/util/res/StringManager.java
@@ -54,7 +54,8 @@ public class StringManager {
/**
* Creates a new StringManager for a given package. This is a private method and all access to it is arbitrated by
- * the static getManager method call so that only one StringManager per package will be created.
+ * the static getManager method call so that only one StringManager per package and Locale combination will be
+ * created. Created managers are held in a per package LRU cache (see {@link #getManager(String, Locale)}).
*
* @param packageName Name of package to create StringManager for.
*/
@@ -215,9 +216,10 @@ public class StringManager {
Map<Locale,StringManager> map = managers.get(packageName);
if (map == null) {
/*
- * Don't want the HashMap size to exceed LOCALE_CACHE_SIZE. Expansion occurs when size() exceeds capacity.
- * Therefore, keep size at or below capacity. removeEldestEntry() executes after insertion therefore the
- * test for removal needs to use one less than the maximum desired size. Note this is an LRU cache.
+ * Note this is an LRU cache. The map holds at most LOCALE_CACHE_SIZE - 1 entries: removeEldestEntry()
+ * executes after insertion, so the test for removal uses one less than the maximum desired size. With the
+ * 0.75 load factor the underlying table resizes when size() exceeds 7, so the capacity argument is not a
+ * size limit.
*/
map = new LinkedHashMap<>(LOCALE_CACHE_SIZE, 0.75f, true) {
@Serial
@@ -241,7 +243,9 @@ public class StringManager {
/**
- * Retrieve the StringManager for a list of Locales. The first StringManager found will be returned.
+ * Retrieve the StringManager for a list of Locales. The first StringManager whose effective locale exactly matches
+ * one of the requested Locales will be returned. Requested Locales that do not match exactly (e.g. regional
+ * variants such as <code>en-US</code>) are skipped.
*
* @param packageName The package for which the StringManager was requested
* @param requestedLocales The list of Locales
diff --git a/java/org/apache/tomcat/util/scan/NonClosingJarInputStream.java b/java/org/apache/tomcat/util/scan/NonClosingJarInputStream.java
index 17e6d9b693..add86e67ec 100644
--- a/java/org/apache/tomcat/util/scan/NonClosingJarInputStream.java
+++ b/java/org/apache/tomcat/util/scan/NonClosingJarInputStream.java
@@ -22,7 +22,7 @@ import java.util.jar.JarInputStream;
/**
* When using a {@link JarInputStream} with an XML parser, the stream will be closed by the parser. This causes problems
- * if multiple entries from the JAR need to be parsed. This implementation makes {{@link #close()} a NO-OP and adds
+ * if multiple entries from the JAR need to be parsed. This implementation makes {@link #close()} a NO-OP and adds
* {@link #reallyClose()} that will close the stream.
*/
public class NonClosingJarInputStream extends JarInputStream {
diff --git a/java/org/apache/tomcat/util/scan/StandardJarScanFilter.java b/java/org/apache/tomcat/util/scan/StandardJarScanFilter.java
index 37b9c05cfb..6744cca901 100644
--- a/java/org/apache/tomcat/util/scan/StandardJarScanFilter.java
+++ b/java/org/apache/tomcat/util/scan/StandardJarScanFilter.java
@@ -66,7 +66,7 @@ public class StandardJarScanFilter implements JarScanFilter {
* <ul>
* <li>JARs that match neither the skip nor the scan list will be included in scan results.</li>
* <li>JARs that match the skip list but not the scan list will be excluded from scan results.</li>
- * <li>JARs that match the scan list will be included from scan results.</li>
+ * <li>JARs that match the scan list will be included in scan results.</li>
* </ul>
* The default skip list and default scan list are obtained from the system properties
* {@link Constants#SKIP_JARS_PROPERTY} and {@link Constants#SCAN_JARS_PROPERTY} respectively. These default values
diff --git a/java/org/apache/tomcat/util/scan/StandardJarScanner.java b/java/org/apache/tomcat/util/scan/StandardJarScanner.java
index f985f4a9dd..da1fa5468b 100644
--- a/java/org/apache/tomcat/util/scan/StandardJarScanner.java
+++ b/java/org/apache/tomcat/util/scan/StandardJarScanner.java
@@ -133,7 +133,7 @@ public class StandardJarScanner implements JarScanner {
}
/**
- * Controls the testing all files to see of they are JAR files extension.
+ * Controls the testing all files to see if they are JAR files extension.
*/
private boolean scanAllFiles = false;
@@ -156,7 +156,7 @@ public class StandardJarScanner implements JarScanner {
}
/**
- * Controls the testing all directories to see of they are exploded JAR files extension.
+ * Controls the testing all directories to see if they are exploded JAR files extension.
*/
private boolean scanAllDirectories = true;
diff --git a/java/org/apache/tomcat/util/security/Escape.java b/java/org/apache/tomcat/util/security/Escape.java
index f2d79b7f7e..e838fdc9f6 100644
--- a/java/org/apache/tomcat/util/security/Escape.java
+++ b/java/org/apache/tomcat/util/security/Escape.java
@@ -90,7 +90,7 @@ public class Escape {
*
* @param content The content to escape
*
- * @return The escaped content converted to String or {@code ?} if the content was {@code null}
+ * @return The escaped content converted to String or <code>&#63;</code> if the content was {@code null}
*/
public static String xml(Object content) {
if (content == null) {
diff --git a/java/org/apache/tomcat/util/security/LocalStrings.properties b/java/org/apache/tomcat/util/security/LocalStrings.properties
index 577cd38463..a8378b2a6c 100644
--- a/java/org/apache/tomcat/util/security/LocalStrings.properties
+++ b/java/org/apache/tomcat/util/security/LocalStrings.properties
@@ -13,4 +13,4 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-concurrentMessageDigest.noDigest=Digest algorithm unavailable
+concurrentMessageDigest.noDigest=Digest algorithm not initialized or unavailable
diff --git a/java/org/apache/tomcat/util/threads/LimitLatch.java b/java/org/apache/tomcat/util/threads/LimitLatch.java
index e2af2ec1de..dd08dbdb58 100644
--- a/java/org/apache/tomcat/util/threads/LimitLatch.java
+++ b/java/org/apache/tomcat/util/threads/LimitLatch.java
@@ -119,7 +119,7 @@ public class LimitLatch {
/**
- * Acquires a shared latch if one is available or waits for one if no shared latch is current available.
+ * Acquires a shared latch if one is available or waits for one if no shared latch is currently available.
*
* @throws InterruptedException If the current thread is interrupted
*/
@@ -145,7 +145,9 @@ public class LimitLatch {
}
/**
- * Releases all waiting threads and causes the {@link #limit} to be ignored until {@link #reset()} is called.
+ * Releases all waiting threads and causes the {@link #limit} to be ignored until {@link #reset()} is called. Note
+ * that this method also decrements the acquisition counter by one as a side effect, so {@link #reset()} should be
+ * called (or a new {@link LimitLatch} used) before the limit is enforced again.
*
* @return <code>true</code> if release was done
*/
diff --git a/java/org/apache/tomcat/util/threads/TaskQueue.java b/java/org/apache/tomcat/util/threads/TaskQueue.java
index b973f73874..3f69271aa0 100644
--- a/java/org/apache/tomcat/util/threads/TaskQueue.java
+++ b/java/org/apache/tomcat/util/threads/TaskQueue.java
@@ -25,9 +25,11 @@ import java.util.concurrent.TimeUnit;
import org.apache.tomcat.util.res.StringManager;
/**
- * As task queue specifically designed to run with a thread pool executor. The task queue is optimised to properly
- * utilize threads within a thread pool executor. If you use a normal queue, the executor will spawn threads when there
- * are idle threads and you won't be able to force items onto the queue itself.
+ * A task queue specifically designed to run with a thread pool executor. The task queue is optimised to properly
+ * utilize threads within a thread pool executor. A normal queue causes the executor to queue tasks first and only
+ * create new threads once the queue is full. This queue instead refuses to queue a task while all existing threads
+ * are busy and the pool size is below its maximum, so the executor creates a new thread for the task instead. It also
+ * supports forcing items onto the queue via {@link #force(Runnable)}.
*/
public class TaskQueue extends LinkedBlockingQueue<Runnable> implements RetryableQueue<Runnable> {
@@ -110,6 +112,18 @@ public class TaskQueue extends LinkedBlockingQueue<Runnable> implements Retryabl
}
+ /**
+ * Removes and returns the head of this queue, waiting up to the specified wait time if necessary for an element to
+ * become available.
+ *
+ * @param timeout the maximum time to wait
+ * @param unit the time unit of the timeout argument
+ *
+ * @return the head of this queue, or {@code null} if the specified waiting time elapses before an element becomes
+ * available
+ * @throws InterruptedException if interrupted while waiting
+ * @throws StopPooledThreadException if the current thread is due to be stopped by the parent executor
+ */
@Override
public Runnable poll(long timeout, TimeUnit unit) throws InterruptedException {
Runnable runnable = super.poll(timeout, unit);
diff --git a/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java b/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java
index 8b53bcf47d..1e44bb8776 100644
--- a/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java
+++ b/java/org/apache/tomcat/util/threads/ThreadPoolExecutor.java
@@ -213,8 +213,6 @@ import org.apache.tomcat.util.res.StringManager;
* }
* }
* }}</pre>
- *
- * @since 1.5
*/
public class ThreadPoolExecutor extends AbstractExecutorService {
@@ -1525,7 +1523,7 @@ public class ThreadPoolExecutor extends AbstractExecutorService {
/**
* Sets the delay in milliseconds after which threads should be renewed.
*
- * @param threadRenewalDelay the renewal delay
+ * @param threadRenewalDelay the renewal delay (a negative value disables thread renewal)
*/
public void setThreadRenewalDelay(long threadRenewalDelay) {
this.threadRenewalDelay = threadRenewalDelay;
@@ -1723,7 +1721,7 @@ public class ThreadPoolExecutor extends AbstractExecutorService {
/**
- * Returns the total number of tasks that have been submitted to this pool.
+ * Returns the number of tasks that have been submitted to this pool and not yet completed.
*
* @return the submitted task count
*/
diff --git a/java/org/apache/tomcat/util/xreflection/ObjectReflectionPropertyInspector.java b/java/org/apache/tomcat/util/xreflection/ObjectReflectionPropertyInspector.java
index dad275cedd..6820e531d0 100644
--- a/java/org/apache/tomcat/util/xreflection/ObjectReflectionPropertyInspector.java
+++ b/java/org/apache/tomcat/util/xreflection/ObjectReflectionPropertyInspector.java
@@ -105,7 +105,7 @@ public final class ObjectReflectionPropertyInspector {
Class.forName("org.apache.tomcat.util.net.SocketProperties"))));
}
- // types of properties that IntrospectionUtils.setProperty supports
+ // types of properties that IntrospectionUtils supports (drives field, setter and getter discovery)
private static final Set<Class<?>> ALLOWED_TYPES = Collections.unmodifiableSet(
new LinkedHashSet<>(Arrays.asList(Boolean.TYPE, Boolean.class, Integer.TYPE, Integer.class,
Long.TYPE, Long.class, String.class, InetAddress.class)));
@@ -116,7 +116,8 @@ public final class ObjectReflectionPropertyInspector {
*
* @param baseClasses The classes to process
* @param packageName The package name for generated code
- * @param location The output directory
+ * @param location The output directory (the package sub-directory derived from <code>packageName</code> must
+ * already exist)
* @param className The class name for generated code
* @throws Exception if an error occurs
*/
diff --git a/java/org/apache/tomcat/websocket/AsyncChannelWrapperSecure.java b/java/org/apache/tomcat/websocket/AsyncChannelWrapperSecure.java
index 872f30f189..38a3f8a407 100644
--- a/java/org/apache/tomcat/websocket/AsyncChannelWrapperSecure.java
+++ b/java/org/apache/tomcat/websocket/AsyncChannelWrapperSecure.java
@@ -44,8 +44,7 @@ import org.apache.juli.logging.LogFactory;
import org.apache.tomcat.util.res.StringManager;
/**
- * Wraps the {@link AsynchronousSocketChannel} with SSL/TLS. This needs a lot more testing before it can be considered
- * robust.
+ * Wraps the {@link AsynchronousSocketChannel} with SSL/TLS.
*/
public class AsyncChannelWrapperSecure implements AsyncChannelWrapper {
diff --git a/java/org/apache/tomcat/websocket/Authenticator.java b/java/org/apache/tomcat/websocket/Authenticator.java
index b8ea9a8d73..52151ab3e5 100644
--- a/java/org/apache/tomcat/websocket/Authenticator.java
+++ b/java/org/apache/tomcat/websocket/Authenticator.java
@@ -55,7 +55,7 @@ public abstract class Authenticator {
*
* @throws AuthenticationException When an error occurs
*
- * @deprecated Unused. Will be remove in Tomcat 12. Use
+ * @deprecated Unused. Will be removed in a future release. Use
* {@link #getAuthorization(String, String, String, String, String, String)}
*/
@Deprecated
diff --git a/java/org/apache/tomcat/websocket/Constants.java b/java/org/apache/tomcat/websocket/Constants.java
index 4e529b8b68..05ac17b4b3 100644
--- a/java/org/apache/tomcat/websocket/Constants.java
+++ b/java/org/apache/tomcat/websocket/Constants.java
@@ -54,7 +54,7 @@ public class Constants {
// Internal OP Codes
// RFC 6455 limits OP Codes to 4 bits so these should never clash
- // Always set bit 4 so these will be treated as control codes
+ // Always set the 0x08 bit so these will be treated as control codes
static final byte INTERNAL_OPCODE_FLUSH = 0x18;
// Buffers
diff --git a/java/org/apache/tomcat/websocket/PerMessageDeflate.java b/java/org/apache/tomcat/websocket/PerMessageDeflate.java
index b5bf3df5ee..d1b0dd110a 100644
--- a/java/org/apache/tomcat/websocket/PerMessageDeflate.java
+++ b/java/org/apache/tomcat/websocket/PerMessageDeflate.java
@@ -620,7 +620,8 @@ public class PerMessageDeflate implements Transformation {
uncompressedIntermediateHandler, uncompressedIntermediateHandler, blocking,
writeTimeoutExpiry);
} else if (!fin && full/* note: needsInput is true here */) {
- // Write buffer full and input message not fully read.
+ // Write buffer full and this part's input fully consumed, but the remainder of the message
+ // is not yet read.
// Output and get more data.
compressedPart = new MessagePart(false, getRsv(uncompressedPart), opCode, compressedPayload,
uncompressedIntermediateHandler, uncompressedIntermediateHandler, blocking,
diff --git a/java/org/apache/tomcat/websocket/Util.java b/java/org/apache/tomcat/websocket/Util.java
index 5ab5edc4f7..e33ba12f21 100644
--- a/java/org/apache/tomcat/websocket/Util.java
+++ b/java/org/apache/tomcat/websocket/Util.java
@@ -128,10 +128,9 @@ public class Util {
static byte[] generateRandomBytes(int len) {
- // SecureRandom is not thread-safe so need to make sure only one thread
- // uses it at a time. In theory, the pool could grow to the same size
- // as the number of request processing threads. In reality, it will be
- // a lot smaller.
+ // SecureRandom is thread-safe, but creating instances is expensive, so instances are pooled and one is
+ // handed out to each concurrent user. In theory, the pool could grow to the same size as the number of
+ // request processing threads. In reality, it will be a lot smaller.
// Get a SecureRandom from the pool
SecureRandom sr = randoms.poll();
@@ -150,7 +149,7 @@ public class Util {
byte[] result = new byte[len];
sr.nextBytes(result);
- // Put the SecureRandom back in the poll
+ // Put the SecureRandom back in the pool
randoms.add(sr);
return result;
@@ -297,7 +296,10 @@ public class Util {
*
* @return The coerced value
*
- * @throws IllegalArgumentException If the type is not supported
+ * @throws IllegalArgumentException If the type is not supported
+ * @throws NumberFormatException If the value cannot be parsed as the target numeric type
+ * @throws StringIndexOutOfBoundsException If the target type is <code>char</code> or <code>Character</code>
+ * and the value is empty
*/
public static Object coerceToType(Class<?> type, String value) {
if (type.equals(String.class)) {
diff --git a/java/org/apache/tomcat/websocket/WsFrameBase.java b/java/org/apache/tomcat/websocket/WsFrameBase.java
index 4077c32ae8..52cc3032e2 100644
--- a/java/org/apache/tomcat/websocket/WsFrameBase.java
+++ b/java/org/apache/tomcat/websocket/WsFrameBase.java
@@ -38,8 +38,8 @@ import org.apache.tomcat.util.ExceptionUtils;
import org.apache.tomcat.util.res.StringManager;
/**
- * Takes the ServletInputStream, processes the WebSocket frames it contains and extracts the messages. WebSocket Pings
- * received will be responded to automatically without any action required by the application.
+ * Processes the WebSocket frames read from the connection and extracts the messages. WebSocket Pings received will be
+ * responded to automatically without any action required by the application.
*/
public abstract class WsFrameBase {
@@ -222,7 +222,7 @@ public abstract class WsFrameBase {
// Client data must be masked
throw new WsIOException(new CloseReason(CloseCodes.PROTOCOL_ERROR, sm.getString("wsFrame.notMasked")));
} else if ((b & 0x80) != 0 && !isMasked()) {
- // Server data must not masked
+ // Server data must not be masked
throw new WsIOException(new CloseReason(CloseCodes.PROTOCOL_ERROR, sm.getString("wsFrame.masked")));
}
payloadLength = b & 0x7F;
diff --git a/java/org/apache/tomcat/websocket/WsSession.java b/java/org/apache/tomcat/websocket/WsSession.java
index 3dc324b05f..c8690ad44a 100644
--- a/java/org/apache/tomcat/websocket/WsSession.java
+++ b/java/org/apache/tomcat/websocket/WsSession.java
@@ -138,7 +138,7 @@ public class WsSession implements Session {
* @param secure Was this session initiated over a secure connection?
* @param clientEndpointConfig The configuration information for the client end point
*
- * @throws DeploymentException if an invalid encode is specified
+ * @throws DeploymentException if an invalid encoder is specified
*/
public WsSession(ClientEndpointHolder clientEndpointHolder, WsRemoteEndpointImplBase wsRemoteEndpoint,
WsWebSocketContainer wsWebSocketContainer, List<Extension> negotiatedExtensions, String subProtocol,
@@ -201,7 +201,7 @@ public class WsSession implements Session {
* @param secure Was this session initiated over a secure connection?
* @param serverEndpointConfig The configuration information for the server end point
*
- * @throws DeploymentException if an invalid encode is specified
+ * @throws DeploymentException if an invalid encoder is specified
*/
public WsSession(WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer,
URI requestUri, Map<String,List<String>> requestParameterMap, String queryString, Principal userPrincipal,
@@ -554,8 +554,8 @@ public class WsSession implements Session {
/**
- * WebSocket 1.0. Section 2.1.5. Need internal close method as spec requires that the local endpoint receives a 1006
- * on timeout.
+ * RFC 6455, sections 5.5.1 and 7.4.2. Need internal close method as spec requires that the local endpoint
+ * receives a 1006 on timeout.
*
* @param closeReasonMessage The close reason to pass to the remote endpoint
* @param closeReasonLocal The close reason to pass to the local endpoint
@@ -566,8 +566,8 @@ public class WsSession implements Session {
/**
- * WebSocket 1.0. Section 2.1.5. Need internal close method as spec requires that the local endpoint receives a 1006
- * on timeout.
+ * RFC 6455, sections 5.5.1 and 7.4.2. Need internal close method as spec requires that the local endpoint
+ * receives a 1006 on timeout.
*
* @param closeReasonMessage The close reason to pass to the remote endpoint
* @param closeReasonLocal The close reason to pass to the local endpoint
diff --git a/java/org/apache/tomcat/websocket/WsWebSocketContainer.java b/java/org/apache/tomcat/websocket/WsWebSocketContainer.java
index 32a7e853ff..212451fe4e 100644
--- a/java/org/apache/tomcat/websocket/WsWebSocketContainer.java
+++ b/java/org/apache/tomcat/websocket/WsWebSocketContainer.java
@@ -1039,7 +1039,7 @@ public class WsWebSocketContainer implements WebSocketContainer, BackgroundProce
/**
- * {@inheritDoc} Currently, this implementation does not support any extensions.
+ * {@inheritDoc} Currently, this implementation supports the permessage-deflate extension.
*/
@Override
public Set<Extension> getInstalledExtensions() {
diff --git a/java/org/apache/tomcat/websocket/pojo/PojoMethodMapping.java b/java/org/apache/tomcat/websocket/pojo/PojoMethodMapping.java
index 61a9a30927..9f4defaed3 100644
--- a/java/org/apache/tomcat/websocket/pojo/PojoMethodMapping.java
+++ b/java/org/apache/tomcat/websocket/pojo/PojoMethodMapping.java
@@ -51,8 +51,9 @@ import org.apache.tomcat.websocket.Util;
import org.apache.tomcat.websocket.Util.DecoderMatch;
/**
- * For a POJO class annotated with {@link jakarta.websocket.server.ServerEndpoint}, an instance of this class creates
- * and caches the method handler, method information and parameter information for the onXXX calls.
+ * For a POJO class annotated with {@link jakarta.websocket.server.ServerEndpoint}, an instance of this class caches the
+ * method information and parameter information for the onXXX calls. The message handlers themselves are not cached;
+ * they are created per session from the cached information.
*/
public class PojoMethodMapping {
@@ -72,7 +73,7 @@ public class PojoMethodMapping {
* Create a method mapping for the given POJO
*
* @param clazzPojo POJO implementation class
- * @param decoderClazzes Set of potential decoder classes
+ * @param decoderClazzes List of potential decoder classes
* @param wsPath Path at which the endpoint will be deployed
* @param instanceManager Instance manager to use to create Decoder instances
*
diff --git a/java/org/apache/tomcat/websocket/pojo/PojoPathParam.java b/java/org/apache/tomcat/websocket/pojo/PojoPathParam.java
index 640ee9a244..838af58ddd 100644
--- a/java/org/apache/tomcat/websocket/pojo/PojoPathParam.java
+++ b/java/org/apache/tomcat/websocket/pojo/PojoPathParam.java
@@ -24,8 +24,8 @@ import org.apache.tomcat.websocket.Util;
/**
* Stores the parameter type and name for a parameter that needs to be passed to an onXxx method of
* {@link jakarta.websocket.Endpoint}. The name is only present for parameters annotated with
- * {@link jakarta.websocket.server.PathParam}. For the {@link jakarta.websocket.Session} and {@link java.lang.Throwable}
- * parameters, {@link #getName()} will always return <code>null</code>.
+ * {@link jakarta.websocket.server.PathParam}; for all other parameters, {@link #getName()} will always return
+ * <code>null</code>.
*/
public class PojoPathParam {
diff --git a/java/org/apache/tomcat/websocket/server/WsFrameServer.java b/java/org/apache/tomcat/websocket/server/WsFrameServer.java
index ad4e35702b..71075de9b5 100644
--- a/java/org/apache/tomcat/websocket/server/WsFrameServer.java
+++ b/java/org/apache/tomcat/websocket/server/WsFrameServer.java
@@ -64,7 +64,7 @@ public class WsFrameServer extends WsFrameBase {
/**
- * Called when there is data in the ServletInputStream to process.
+ * Called when there is data in the socket to process.
*
* @throws IOException if an I/O error occurs while processing the available data
*/
diff --git a/java/org/apache/tomcat/websocket/server/WsServerContainer.java b/java/org/apache/tomcat/websocket/server/WsServerContainer.java
index 7f46ed3544..8e7aca7498 100644
--- a/java/org/apache/tomcat/websocket/server/WsServerContainer.java
+++ b/java/org/apache/tomcat/websocket/server/WsServerContainer.java
@@ -106,8 +106,8 @@ public class WsServerContainer extends WsWebSocketContainer implements ServerCon
/**
- * Published the provided endpoint implementation at the specified path with the specified configuration.
- * {@link #WsServerContainer(ServletContext)} must be called before calling this method.
+ * Published the provided endpoint implementation at the specified path with the specified configuration. The
+ * container instance must be fully constructed before calling this method.
*
* @param sec The configuration to use when creating endpoint instances
*
diff --git a/test/org/apache/juli/TestJsonFormatter.java b/test/org/apache/juli/TestJsonFormatter.java
index 9d526058c4..0e52633eaf 100644
--- a/test/org/apache/juli/TestJsonFormatter.java
+++ b/test/org/apache/juli/TestJsonFormatter.java
@@ -74,6 +74,7 @@ public class TestJsonFormatter {
}
}
+ @Test
public void testEscapeLatterHalf() {
String input = "0123456789";
diff --git a/webapps/docs/config/context.xml b/webapps/docs/config/context.xml
index bb4a82d651..2ce00e18e4 100644
--- a/webapps/docs/config/context.xml
+++ b/webapps/docs/config/context.xml
@@ -1433,7 +1433,7 @@
two additional attributes to allow a shared data source to be used with different credentials.
When these two additional attributes are used in combination with the <code>javax.sql.DataSource</code>
type, different contexts can share a global data source with different credentials.
- Under the hood, what happens is that a call to <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.sql/javax/sql/DataSource.html#getConnection())"><code>getConnection()</code></a>
+ Under the hood, what happens is that a call to <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.sql/javax/sql/DataSource.html#getConnection()"><code>getConnection()</code></a>
is simply translated to a call <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.sql/javax/sql/DataSource.html#getConnection(java.lang.String,java.lang.String)">
<code>getConnection(username, password)</code></a> on the global data source. This is an easy way to get code to be transparent to what schemas are being used,
yet be able to control connections (or pools) in the global configuration.
diff --git a/webapps/docs/config/listeners.xml b/webapps/docs/config/listeners.xml
index ac8fc2937e..9df0771b59 100644
--- a/webapps/docs/config/listeners.xml
+++ b/webapps/docs/config/listeners.xml
@@ -629,7 +629,8 @@
<attributes>
<attribute name="Port" required="false">
- <p>Port the connector that will received proxied traffic from HTTPD, default the first connector will be used</p>
+ <p>Port of the connector that will receive proxied traffic from HTTPD, default 8009.
+ Set to 0 to match any port (the first connector will be used)</p>
</attribute>
<attribute name="Host" required="false">
@@ -637,8 +638,8 @@
default empty the <strong>Port</strong> will be used</p>
</attribute>
- <attribute name="proxyURL" required="false">
- <p>proxyURL is the URL corresponding to the <strong>Location</strong> in httpd configuration of the heartbeat Handler,
+ <attribute name="proxyURLString" required="false">
+ <p>proxyURLString is the URL corresponding to the <strong>Location</strong> in httpd configuration of the heartbeat Handler,
default /HeartbeatListener</p>
</attribute>
diff --git a/webapps/docs/monitoring.xml b/webapps/docs/monitoring.xml
index 42c89113c2..2737f6ab55 100644
--- a/webapps/docs/monitoring.xml
+++ b/webapps/docs/monitoring.xml
@@ -204,9 +204,9 @@ senderAddress=${cluster.server.address},senderPort=${cluster.server.port}"
senderObjectNames: ${senderObjectNames.0}
IDataSender.backup.connected: ${IDataSender.backup.connected}
session: ${sessions.0}
-manager.length: ${manager.length}
-manager.0.name: ${manager.0.name}
-manager.1.name: ${manager.1.name}
+manager.Length: ${manager.Length}
+manager.0.Name: ${manager.0.Name}
+manager.1.Name: ${manager.1.Name}
hello: ${Hello}
manager.ClusterTest.0.name: ${manager.ClusterTest.0.name}
manager.ClusterTest.0.activeSessions: ${manager.ClusterTest.0.activeSessions}
@@ -407,7 +407,7 @@ List of Attributes
<tr>
<td>separatearrayresults</td>
<td>When return value is an array, save result as property list
- (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
+ (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.Length</em>)
</td>
<td><code class="noHighlight">true</code></td>
</tr>
@@ -592,7 +592,7 @@ List of Attributes
<tr>
<td>separatearrayresults</td>
<td>When return value is an array, save result as property list
- (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
+ (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.Length</em>)
</td>
<td><code class="noHighlight">true</code></td>
</tr>
@@ -688,7 +688,7 @@ List of Attributes
<tr>
<td>resultproperty</td>
- <td>Prefix project property name to all founded MBeans (<em>mbeans.[0..N].objectname</em>)
+ <td>Prefix project property name to all founded MBeans (<em>mbeans.[0..N].Name</em>)
</td>
<td></td>
</tr>
@@ -711,7 +711,7 @@ List of Attributes
<tr>
<td>separatearrayresults</td>
<td>When return value is an array, save result as property list
- (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.length</em>)
+ (<em>$resultproperty.[0..N]</em> and <em>$resultproperty.Length</em>)
</td>
<td><code class="noHighlight">true</code></td>
</tr>
@@ -725,8 +725,8 @@ Get all Manager ObjectNames from all services and Hosts
name="Catalina:type=Manager,*
resultproperty="manager" />]]></source>
<p>
-Now you can find the Session Manager at <em>${manager.[0..N].name}</em>
-properties and access the result object counter with ${manager.length} property.
+Now you can find the Session Manager at <em>${manager.[0..N].Name}</em>
+properties and access the result object counter with ${manager.Length} property.
</p>
<p>
Example to get the Manager from <em>servlet-examples</em> application an bind all MBean properties
@@ -738,7 +738,7 @@ Example to get the Manager from <em>servlet-examples</em> application an bind al
<p>
Now you can find the manager at <em>${manager.servletExamples.0.name}</em> property
and can access all properties from this manager with <em>${manager.servletExamples.0.[manager attribute names]</em>}.
-The result object counter from MBeans is stored ad ${manager.length} property.
+The result object counter from MBeans is stored ad ${manager.Length} property.
</p>
<p>
@@ -774,7 +774,7 @@ Example to get all MBeans from a server and store inside an external XML propert
<!-- Print results -->
<echo message=
- "Number of MBeans in server ${jmx.host}:${jmx.port} is ${mbeans.length}"/>
+ "Number of MBeans in server ${jmx.host}:${jmx.port} is ${mbeans.Length}"/>
</target>
</project>]]></source>
<p>
diff --git a/webapps/docs/rewrite.xml b/webapps/docs/rewrite.xml
index 27014960d0..c4ad47fce0 100644
--- a/webapps/docs/rewrite.xml
+++ b/webapps/docs/rewrite.xml
@@ -667,7 +667,7 @@ cannot use <code>$N</code> in the substitution string!
is specified by <em>NAME</em> and the value is
<em>VAL</em>. The <em>domain</em> field is the domain of the
cookie, such as '.apache.org', the optional <em>lifetime</em>
- is the lifetime of the cookie in minutes, and the optional
+ is the lifetime of the cookie in seconds, and the optional
<em>path</em> is the path of the cookie</li>
<li>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org