Polishing

spring-context/src/main/java/org/springframework/context/support/DefaultLifecycleProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -45,7 +45,11 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
- * Default implementation of the {@link LifecycleProcessor} strategy.
+ * Spring's default implementation of the {@link LifecycleProcessor} strategy.
+ *
+ * <p>Provides interaction with {@link Lifecycle} and {@link SmartLifecycle} beans in
+ * groups for specific phases, on startup/shutdown as well as for explicit start/stop
+ * interactions on a {@link org.springframework.context.ConfigurableApplicationContext}.
  *
  * @author Mark Fisher
  * @author Juergen Hoeller
@@ -314,6 +318,8 @@ public class DefaultLifecycleProcessor implements LifecycleProcessor, BeanFactor
 	/**
 	 * Helper class for maintaining a group of Lifecycle beans that should be started
 	 * and stopped together based on their 'phase' value (or the default value of 0).
+	 * The group is expected to be created in an ad-hoc fashion and group members are
+	 * expected to always have the same 'phase' value.
 	 */
 	private class LifecycleGroup {
 

spring-context/src/main/java/org/springframework/scheduling/concurrent/ExecutorConfigurationSupport.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -73,7 +73,7 @@ public abstract class ExecutorConfigurationSupport extends CustomizableThreadFac
 
 	/**
 	 * Set the ThreadFactory to use for the ExecutorService's thread pool.
-	 * Default is the underlying ExecutorService's default thread factory.
+	 * The default is the underlying ExecutorService's default thread factory.
 	 * <p>In a Jakarta EE or other managed environment with JSR-236 support,
 	 * consider specifying a JNDI-located ManagedThreadFactory: by default,
 	 * to be found at "java:comp/DefaultManagedThreadFactory".
@@ -108,7 +108,7 @@ public abstract class ExecutorConfigurationSupport extends CustomizableThreadFac
 	/**
 	 * Set whether to wait for scheduled tasks to complete on shutdown,
 	 * not interrupting running tasks and executing all tasks in the queue.
-	 * <p>Default is {@code false}, shutting down immediately through interrupting
+	 * <p>The default is {@code false}, shutting down immediately through interrupting
 	 * ongoing tasks and clearing the queue. Switch this flag to {@code true} if
 	 * you prefer fully completed tasks at the expense of a longer shutdown phase.
 	 * <p>Note that Spring's container shutdown continues while ongoing tasks
@@ -119,6 +119,8 @@ public abstract class ExecutorConfigurationSupport extends CustomizableThreadFac
 	 * property instead of or in addition to this property.
 	 * @see java.util.concurrent.ExecutorService#shutdown()
 	 * @see java.util.concurrent.ExecutorService#shutdownNow()
+	 * @see #shutdown()
+	 * @see #setAwaitTerminationSeconds
 	 */
 	public void setWaitForTasksToCompleteOnShutdown(boolean waitForJobsToCompleteOnShutdown) {
 		this.waitForTasksToCompleteOnShutdown = waitForJobsToCompleteOnShutdown;
@@ -237,7 +239,7 @@ public abstract class ExecutorConfigurationSupport extends CustomizableThreadFac
 	}
 
 	/**
-	 * Cancel the given remaining task which never commended execution,
+	 * Cancel the given remaining task which never commenced execution,
 	 * as returned from {@link ExecutorService#shutdownNow()}.
 	 * @param task the task to cancel (typically a {@link RunnableFuture})
 	 * @since 5.0.5

spring-context/src/test/java/org/springframework/scheduling/support/BitsCronFieldTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -51,7 +51,6 @@ class BitsCronFieldTests {
 		assertThat(BitsCronField.parseMonth("1")).has(set(1)).has(clearRange(2, 12));
 
 		assertThat(BitsCronField.parseDaysOfWeek("0")).has(set(7, 7)).has(clearRange(0, 6));
-
 		assertThat(BitsCronField.parseDaysOfWeek("7-5")).has(clear(0)).has(setRange(1, 5))
 				.has(clear(6)).has(set(7));
 	}

spring-context/src/test/java/org/springframework/scheduling/support/QuartzCronFieldTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -74,6 +74,7 @@ class QuartzCronFieldTests {
 
 	@Test
 	void dayOfWeek_0(){
+		// third Sunday (0) of the month
 		QuartzCronField field = QuartzCronField.parseDaysOfWeek("0#3");
 
 		LocalDate last = LocalDate.of(2024, 1, 1);
@@ -83,6 +84,7 @@ class QuartzCronFieldTests {
 
 	@Test
 	void dayOfWeek_1(){
+		// third Monday (1) of the month
 		QuartzCronField field = QuartzCronField.parseDaysOfWeek("1#3");
 
 		LocalDate last = LocalDate.of(2024, 1, 1);
@@ -92,6 +94,7 @@ class QuartzCronFieldTests {
 
 	@Test
 	void dayOfWeek_2(){
+		// third Tuesday (2) of the month
 		QuartzCronField field = QuartzCronField.parseDaysOfWeek("2#3");
 
 		LocalDate last = LocalDate.of(2024, 1, 1);
@@ -101,6 +104,7 @@ class QuartzCronFieldTests {
 
 	@Test
 	void dayOfWeek_7() {
+		// third Sunday (7 as alternative to 0) of the month
 		QuartzCronField field = QuartzCronField.parseDaysOfWeek("7#3");
 
 		LocalDate last = LocalDate.of(2024, 1, 1);

spring-jdbc/src/main/java/org/springframework/jdbc/core/metadata/GenericTableMetaDataProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -158,7 +158,7 @@ public class GenericTableMetaDataProvider implements TableMetaDataProvider {
 		}
 		catch (SQLException ex) {
 			if (logger.isWarnEnabled()) {
-				logger.warn("Error retrieving 'DatabaseMetaData.getGeneratedKeys': " + ex.getMessage());
+				logger.warn("Error retrieving 'DatabaseMetaData.supportsGetGeneratedKeys': " + ex.getMessage());
 			}
 		}
 		try {
@@ -290,7 +290,7 @@ public class GenericTableMetaDataProvider implements TableMetaDataProvider {
 	}
 
 	/**
-	 * Provide access to default schema for subclasses.
+	 * Provide access to the default schema for subclasses.
 	 */
 	@Nullable
 	protected String getDefaultSchema() {
@@ -298,7 +298,7 @@ public class GenericTableMetaDataProvider implements TableMetaDataProvider {
 	}
 
 	/**
-	 * Provide access to version info for subclasses.
+	 * Provide access to the version info for subclasses.
 	 */
 	@Nullable
 	protected String getDatabaseVersion() {

spring-jdbc/src/main/java/org/springframework/jdbc/core/metadata/TableMetaDataContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -63,9 +63,6 @@ public class TableMetaDataContext {
 	@Nullable
 	private String schemaName;
 
-	// List of columns objects to be used in this context
-	private List<String> tableColumns = new ArrayList<>();
-
 	// Should we access insert parameter meta-data info or not
 	private boolean accessTableColumnMetaData = true;
 
@@ -76,6 +73,9 @@ public class TableMetaDataContext {
 	@Nullable
 	private TableMetaDataProvider metaDataProvider;
 
+	// List of columns objects to be used in this context
+	private List<String> tableColumns = new ArrayList<>();
+
 	// Are we using generated key columns
 	private boolean generatedKeyColumnsUsed = false;
 
@@ -139,7 +139,6 @@ public class TableMetaDataContext {
 		return this.accessTableColumnMetaData;
 	}
 
-
 	/**
 	 * Specify whether we should override default for accessing synonyms.
 	 */
@@ -266,7 +265,6 @@ public class TableMetaDataContext {
 		return values;
 	}
 
-
 	/**
 	 * Build the insert string based on configuration and meta-data information.
 	 * @return the insert string to be used
@@ -303,8 +301,8 @@ public class TableMetaDataContext {
 				}
 			}
 			else {
-				String message = "Unable to locate columns for table '" + getTableName()
-						+ "' so an insert statement can't be generated.";
+				String message = "Unable to locate columns for table '" + getTableName() +
+						"' so an insert statement can't be generated.";
 				if (isAccessTableColumnMetaData()) {
 					message += " Consider specifying explicit column names -- for example, via SimpleJdbcInsert#usingColumns().";
 				}
@@ -349,26 +347,27 @@ public class TableMetaDataContext {
 
 
 	/**
-	 * Does this database support the JDBC 3.0 feature of retrieving generated keys:
-	 * {@link java.sql.DatabaseMetaData#supportsGetGeneratedKeys()}?
+	 * Does this database support the JDBC feature for retrieving generated keys?
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	public boolean isGetGeneratedKeysSupported() {
 		return obtainMetaDataProvider().isGetGeneratedKeysSupported();
 	}
 
 	/**
-	 * Does this database support simple query to retrieve generated keys
-	 * when the JDBC 3.0 feature is not supported:
-	 * {@link java.sql.DatabaseMetaData#supportsGetGeneratedKeys()}?
+	 * Does this database support a simple query to retrieve generated keys when
+	 * the JDBC feature for retrieving generated keys is not supported?
+	 * @see #isGetGeneratedKeysSupported()
+	 * @see #getSimpleQueryForGetGeneratedKey(String, String)
 	 */
 	public boolean isGetGeneratedKeysSimulated() {
 		return obtainMetaDataProvider().isGetGeneratedKeysSimulated();
 	}
 
 	/**
-	 * Does this database support a simple query to retrieve generated keys
-	 * when the JDBC 3.0 feature is not supported:
-	 * {@link java.sql.DatabaseMetaData#supportsGetGeneratedKeys()}?
+	 * Get the simple query to retrieve generated keys when the JDBC feature for
+	 * retrieving generated keys is not supported.
+	 * @see #isGetGeneratedKeysSimulated()
 	 */
 	@Nullable
 	public String getSimpleQueryForGetGeneratedKey(String tableName, String keyColumnName) {
@@ -376,8 +375,9 @@ public class TableMetaDataContext {
 	}
 
 	/**
-	 * Is a column name String array for retrieving generated keys supported:
-	 * {@link java.sql.Connection#createStruct(String, Object[])}?
+	 * Does this database support a column name String array for retrieving generated
+	 * keys?
+	 * @see java.sql.Connection#createStruct(String, Object[])
 	 */
 	public boolean isGeneratedKeysColumnNameArraySupported() {
 		return obtainMetaDataProvider().isGeneratedKeysColumnNameArraySupported();