Extend query hints support across JPA Item Readers

Enhanced `JpaCursorItemReader`, `JpaCursorItemReaderBuilder`, `JpaPagingItemReader`, and `JpaPagingItemReaderBuilder` with query hints configuration. The inclusion of query hints in both cursor and paging item readers improves query execution strategies, optimizing performance for complex data retrieval scenarios.

Author: baezzys

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/JpaCursorItemReader.java

@@ -43,6 +43,7 @@
  * The implementation is <b>not</b> thread-safe.
  *
  * @author Mahmoud Ben Hassine
+ * @author Jinwoo Bae
  * @param <T> type of items to read
  * @since 4.3
  */
@@ -58,6 +59,8 @@ public class JpaCursorItemReader<T> extends AbstractItemCountingItemStreamItemRe
 
 	private Map<String, Object> parameterValues;
 
+	private Map<String, Object> hintValues;
+
 	private Iterator<T> iterator;
 
 	/**
@@ -100,6 +103,16 @@ public void setParameterValues(Map<String, Object> parameterValues) {
 		this.parameterValues = parameterValues;
 	}
 
+	/**
+	 * Set the query hint values for the JPA query. Query hints can be used to give
+	 * instructions to the JPA provider
+	 * @param hintValues a map where each key is the name of the hint, and the corresponding
+	 * value is the hint value.
+	 */
+	public void setHintValues(Map<String, Object> hintValues) {
+		this.hintValues = hintValues;
+	}
+
 	@Override
 	public void afterPropertiesSet() throws Exception {
 		Assert.state(this.entityManagerFactory != null, "EntityManagerFactory is required");
@@ -123,6 +136,10 @@ protected void doOpen() throws Exception {
 		if (this.parameterValues != null) {
 			this.parameterValues.forEach(query::setParameter);
 		}
+		if (this.hintValues != null) {
+			this.hintValues.forEach(query::setHint);
+		}
+
 		this.iterator = query.getResultStream().iterator();
 	}
 

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/JpaPagingItemReader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -80,6 +80,7 @@
  * @author Dave Syer
  * @author Will Schipp
  * @author Mahmoud Ben Hassine
+ * @author Jinwoo Bae
  * @since 2.0
  */
 public class JpaPagingItemReader<T> extends AbstractPagingItemReader<T> {
@@ -96,6 +97,8 @@ public class JpaPagingItemReader<T> extends AbstractPagingItemReader<T> {
 
 	private Map<String, Object> parameterValues;
 
+	private Map<String, Object> hintValues;
+
 	private boolean transacted = true;// default value
 
 	public JpaPagingItemReader() {
@@ -128,6 +131,17 @@ public void setParameterValues(Map<String, Object> parameterValues) {
 		this.parameterValues = parameterValues;
 	}
 
+	/**
+	 * Set the query hint values for the JPA query. Query hints can be used to give
+	 * instructions to the JPA provider
+	 * @param hintValues a map where each key is the name of the hint, and the corresponding
+	 * value is the hint's value.
+	 */
+	public void setHintValues(Map<String, Object> hintValues) {
+		this.hintValues = hintValues;
+	}
+
+
 	/**
 	 * By default (true) the EntityTransaction will be started and committed around the
 	 * read. Can be overridden (false) in cases where the JPA implementation doesn't
@@ -202,6 +216,10 @@ protected void doReadPage() {
 			}
 		}
 
+		if (this.hintValues != null) {
+			this.hintValues.forEach(query::setHint);
+		}
+
 		if (results == null) {
 			results = new CopyOnWriteArrayList<>();
 		}

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/builder/JpaCursorItemReaderBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2021 the original author or authors.
+ * Copyright 2020-2023 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.
@@ -30,6 +30,7 @@
  * Builder for {@link JpaCursorItemReader}.
  *
  * @author Mahmoud Ben Hassine
+ * @author Jinwoo Bae
  * @since 4.3
  */
 public class JpaCursorItemReaderBuilder<T> {
@@ -42,6 +43,8 @@ public class JpaCursorItemReaderBuilder<T> {
 
 	private Map<String, Object> parameterValues;
 
+	private Map<String, Object> hintValues;
+
 	private boolean saveState = true;
 
 	private String name;
@@ -112,6 +115,18 @@ public JpaCursorItemReaderBuilder<T> parameterValues(Map<String, Object> paramet
 		return this;
 	}
 
+	/**
+	 * A map of hint values to be set on the query. The key of the map is the name of
+	 * the hint to be applied, with the value being the specific setting for that hint.
+	 * @param hintValues map of query hints
+	 * @return this instance for method chaining
+	 * @see JpaCursorItemReader#setHintValues(Map)
+	 */
+	public JpaCursorItemReaderBuilder<T> queryHints(Map<String, Object> hintValues) {
+		this.hintValues = hintValues;
+		return this;
+	}
+
 	/**
 	 * A query provider. This should be set only if {@link #queryString(String)} have not
 	 * been set.
@@ -169,10 +184,12 @@ public JpaCursorItemReader<T> build() {
 		reader.setQueryProvider(this.queryProvider);
 		reader.setQueryString(this.queryString);
 		reader.setParameterValues(this.parameterValues);
+		reader.setHintValues(this.hintValues);
 		reader.setCurrentItemCount(this.currentItemCount);
 		reader.setMaxItemCount(this.maxItemCount);
 		reader.setSaveState(this.saveState);
 		reader.setName(this.name);
+
 		return reader;
 	}
 

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/builder/JpaPagingItemReaderBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2021 the original author or authors.
+ * Copyright 2017-2023 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.
@@ -27,6 +27,7 @@
  *
  * @author Michael Minella
  * @author Glenn Renfro
+ * @author Jinwoo Bae
  * @since 4.0
  */
 
@@ -38,6 +39,8 @@ public class JpaPagingItemReaderBuilder<T> {
 
 	private Map<String, Object> parameterValues;
 
+	private Map<String, Object> hintValues;
+
 	private boolean transacted = true;
 
 	private String queryString;
@@ -129,6 +132,18 @@ public JpaPagingItemReaderBuilder<T> parameterValues(Map<String, Object> paramet
 		return this;
 	}
 
+	/**
+	 * A map of hint values to be set on the query. The key of the map is the name of
+	 * the hint to be applied, with the value being the specific setting for that hint.
+	 * @param hintValues map of query hints
+	 * @return this instance for method chaining
+	 * @see JpaPagingItemReader#setHintValues(Map)
+	 */
+	public JpaPagingItemReaderBuilder<T> queryHints(Map<String, Object> hintValues) {
+		this.hintValues = hintValues;
+		return this;
+	}
+
 	/**
 	 * A query provider. This should be set only if {@link #queryString(String)} have not
 	 * been set.
@@ -204,6 +219,7 @@ public JpaPagingItemReader<T> build() {
 		reader.setQueryString(this.queryString);
 		reader.setPageSize(this.pageSize);
 		reader.setParameterValues(this.parameterValues);
+		reader.setHintValues(this.hintValues);
 		reader.setEntityManagerFactory(this.entityManagerFactory);
 		reader.setQueryProvider(this.queryProvider);
 		reader.setTransacted(this.transacted);

spring-batch-infrastructure/src/test/java/org/springframework/batch/item/database/builder/JpaCursorItemReaderBuilderTests.java

@@ -74,11 +74,11 @@ void tearDown() {
 	@Test
 	void testConfiguration() throws Exception {
 		JpaCursorItemReader<Foo> reader = new JpaCursorItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.currentItemCount(2)
-			.maxItemCount(4)
-			.queryString("select f from Foo f ")
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.currentItemCount(2)
+				.maxItemCount(4)
+				.queryString("select f from Foo f ")
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -107,11 +107,11 @@ void testConfigurationNoSaveState() throws Exception {
 		parameters.put("value", 2);
 
 		JpaCursorItemReader<Foo> reader = new JpaCursorItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.queryString("select f from Foo f where f.id > :value")
-			.parameterValues(parameters)
-			.saveState(false)
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.queryString("select f from Foo f where f.id > :value")
+				.parameterValues(parameters)
+				.saveState(false)
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -139,9 +139,9 @@ void testConfigurationNamedQueryProvider() throws Exception {
 		namedQueryProvider.afterPropertiesSet();
 
 		JpaCursorItemReader<Foo> reader = new JpaCursorItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.queryProvider(namedQueryProvider)
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.queryProvider(namedQueryProvider)
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -173,9 +173,9 @@ void testConfigurationNativeQueryProvider() throws Exception {
 		provider.afterPropertiesSet();
 
 		JpaCursorItemReader<Foo> reader = new JpaCursorItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.queryProvider(provider)
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.queryProvider(provider)
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -205,7 +205,7 @@ void testValidation() {
 		assertEquals("A name is required when saveState is set to true", exception.getMessage());
 
 		builder = new JpaCursorItemReaderBuilder<Foo>().entityManagerFactory(this.entityManagerFactory)
-			.saveState(false);
+				.saveState(false);
 		exception = assertThrows(IllegalArgumentException.class, builder::build);
 		assertEquals("Query string is required when queryProvider is null", exception.getMessage());
 	}
@@ -242,4 +242,4 @@ public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
 
 	}
 
-}
+}

spring-batch-infrastructure/src/test/java/org/springframework/batch/item/database/builder/JpaPagingItemReaderBuilderTests.java

@@ -77,13 +77,13 @@ void tearDown() {
 	@Test
 	void testConfiguration() throws Exception {
 		JpaPagingItemReader<Foo> reader = new JpaPagingItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.currentItemCount(2)
-			.maxItemCount(4)
-			.pageSize(5)
-			.transacted(false)
-			.queryString("select f from Foo f ")
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.currentItemCount(2)
+				.maxItemCount(4)
+				.pageSize(5)
+				.transacted(false)
+				.queryString("select f from Foo f ")
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -114,11 +114,11 @@ void testConfigurationNoSaveState() throws Exception {
 		parameters.put("value", 2);
 
 		JpaPagingItemReader<Foo> reader = new JpaPagingItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.queryString("select f from Foo f where f.id > :value")
-			.parameterValues(parameters)
-			.saveState(false)
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.queryString("select f from Foo f where f.id > :value")
+				.parameterValues(parameters)
+				.saveState(false)
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -146,9 +146,9 @@ void testConfigurationNamedQueryProvider() throws Exception {
 		namedQueryProvider.afterPropertiesSet();
 
 		JpaPagingItemReader<Foo> reader = new JpaPagingItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.queryProvider(namedQueryProvider)
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.queryProvider(namedQueryProvider)
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -180,9 +180,9 @@ void testConfigurationNativeQueryProvider() throws Exception {
 		provider.afterPropertiesSet();
 
 		JpaPagingItemReader<Foo> reader = new JpaPagingItemReaderBuilder<Foo>().name("fooReader")
-			.entityManagerFactory(this.entityManagerFactory)
-			.queryProvider(provider)
-			.build();
+				.entityManagerFactory(this.entityManagerFactory)
+				.queryProvider(provider)
+				.build();
 
 		reader.afterPropertiesSet();
 
@@ -204,7 +204,7 @@ void testConfigurationNativeQueryProvider() throws Exception {
 	@Test
 	void testValidation() {
 		var builder = new JpaPagingItemReaderBuilder<Foo>().entityManagerFactory(this.entityManagerFactory)
-			.pageSize(-2);
+				.pageSize(-2);
 		Exception exception = assertThrows(IllegalArgumentException.class, builder::build);
 		assertEquals("pageSize must be greater than zero", exception.getMessage());
 
@@ -217,7 +217,7 @@ void testValidation() {
 		assertEquals("A name is required when saveState is set to true", exception.getMessage());
 
 		builder = new JpaPagingItemReaderBuilder<Foo>().entityManagerFactory(this.entityManagerFactory)
-			.saveState(false);
+				.saveState(false);
 		exception = assertThrows(IllegalArgumentException.class, builder::build);
 		assertEquals("Query string is required when queryProvider is null", exception.getMessage());
 	}
@@ -254,4 +254,4 @@ public LocalContainerEntityManagerFactoryBean entityManagerFactory() throws Exce
 
 	}
 
-}
+}