GEOT-7564 Allow to skip check on staleness of index files on IndexManager

[vittoema96]

When loading a shapefile, a check is made to ensure that the index files (.qif/.fix) are not "stale". This is done by comparing lastModified times of .shp and indexes files, if the latter are <= that .shp's lastModified the indexes are recreated.
The problem is that when files are copied, they will be considered stale and geotools will waste time recreating them.

I propose a new property to skip this check.

The changes are the following:

• ShapefileDataStore now has an attribute (ignoreIndexStaleness), with its getter and setter methods
• IndexManager now checks index staleness only if ShapefileDataStore's ignoreIndexStaleness is False
• ShapefileDataStoreFactory has a new Param "IGNORE_STALENESS"
• shape.rst was updated with the new parameter
• unit tests were made to check the new code

Checklist

• I have read the contribution guidelines.
• I have sent a Contribution Licence Agreement (not required for small changes, e.g., fixing typos in documentation).
• First PR targets the main branch (backports managed later; ignore for branch specific issues).
• Avoid Java 9+ split packages.
• All the build checks are green (see automated QA checks).

For core and extension modules:

• New unit tests have been added covering the changes.
• Documentation has been updated (if change is visible to end users).
• There is an issue in GeoTools Jira (except for changes not visible to end users).
• Commit message(s) must be in the form [GEOT-XYZW] Title of the Jira ticket.
• The commit targets a single objective (if multiple focuses cannot be avoided, each one is in its own commit, and has a separate ticket describing it).
• Bug fixes and small new features are presented as a single commit.

[aaime]

I'm familiar with the issue and believe the new flag is fine.

One of the Linux build failed on the new test:

2024-05-09T09:13:10.7100635Z 09:13:10,694 [ERROR] Tests run: 60, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 2.563 s <<< FAILURE! - in org.geotools.data.shapefile.ShapefileDataStoreTest
2024-05-09T09:13:10.7128142Z 09:13:10,694 [ERROR] testIgnoreIndexStaleness(org.geotools.data.shapefile.ShapefileDataStoreTest)  Time elapsed: 0.031 s  <<< FAILURE!
2024-05-09T09:13:10.7130112Z java.lang.AssertionError
2024-05-09T09:13:10.7130819Z 	at org.junit.Assert.fail(Assert.java:87)
2024-05-09T09:13:10.7131717Z 	at org.junit.Assert.assertTrue(Assert.java:42)
2024-05-09T09:13:10.7132586Z 	at org.junit.Assert.assertTrue(Assert.java:53)
2024-05-09T09:13:10.7134101Z 	at org.geotools.data.shapefile.ShapefileDataStoreTest.testIgnoreIndexStaleness(ShapefileDataStoreTest.java:2109)

I did not check the test sources in detail, but the Github action VMs tend to be pretty slow and have erratic behavior time wise, please double check you're allowing plenty of time for tests to run. In GeoServer we use awaitility for this kind of test, it can check a condition periodically, exit as soon as it passes, but also allow a max wait and then fail.... It's also possible to implement something like that manually using short sleeps in a loop.

Also, the QA build is failing due to formatting errors:

Error:  Failed to execute goal com.diffplug.spotless:spotless-maven-plugin:2.20.0:check (default) on project gt-shapefile: The following files had format violations:
Error:      src/main/java/org/geotools/data/shapefile/IndexManager.java
Error:          @@ -237,7 +237,7 @@
Error:           
Error:           ············File·indexFile·=·URLs.urlToFile(indexURL);
Error:           ············File·shpFile·=·URLs.urlToFile(shpURL);
Error:          -············
Error:          +
Error:           ············if·(store.ignoreIndexStaleness)·return·!indexFile.exists();
Error:           
Error:           ············long·indexLastModified·=·indexFile.lastModified();
Error:      src/test/java/org/geotools/data/shapefile/ShapefileDataStoreTest.java
Error:          @@ -2097,22 +2097,23 @@
Error:           
Error:           ········assertFalse(ds.indexManager.isIndexStale(fix));·//·indexes·are·no·longer·considered·stale
Error:           
Error:          -········try(SimpleFeatureIterator·sfi·=·fs.getFeatures(Query.ALL).features()){};
Error:          +········try·(SimpleFeatureIterator·sfi·=·fs.getFeatures(Query.ALL).features())·{}
Error:          +········;
Error:           ········assertEquals(fixModified,·fixFile.lastModified());
Error:           
Error:           ········ds.setIgnoreIndexStaleness(false);
Error:           ········assertTrue(ds.indexManager.isIndexStale(fix));
Error:           
Error:          -········try(SimpleFeatureIterator·sfi·=·fs.getFeatures(Query.ALL).features()){};
Error:          +········try·(SimpleFeatureIterator·sfi·=·fs.getFeatures(Query.ALL).features())·{}
Error:          +········;
Error:           ········assertTrue(fixModified·<·fixFile.lastModified());
Error:           
Error:           ········ds.dispose();
Error:           ····}
Error:           
Error:          -
Error:           ····@Test
Error:           ····public·void·testIgnoreIndexStalenessFactoryParam()·throws·Exception·{
Error:          -········for(boolean·mustIgnore·:·new·boolean[]{true,·false})·{
Error:          +········for·(boolean·mustIgnore·:·new·boolean[]·{true,·false})·{
Error:           ············ShapefileDataStoreFactory·factory·=·new·ShapefileDataStoreFactory();
Error:           
Error:           ············Map<String,·Serializable>·map·=·new·HashMap<>();
Error:          @@ -2124,5 +2125,4 @@
Error:           ············store.dispose();
Error:           ········}
Error:           ····}
Error:          -
Error:           }
Error:  Run 'mvn spotless:apply' to fix these violations.

Building with Maven from the command line automatically fixes the sources, while you're at it I'd recommend doing on build with "-Dqa" to enable all QA tools locally. See the QA guide for more information.

[aaime]

The test keeps on failing, please have a look at it:

2024-05-14T09:58:11.0014726Z [ERROR] Tests run: 60, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.929 s <<< FAILURE! - in org.geotools.data.shapefile.ShapefileDataStoreTest
2024-05-14T09:58:11.0016975Z [ERROR] testIgnoreIndexStaleness(org.geotools.data.shapefile.ShapefileDataStoreTest)  Time elapsed: 0.013 s  <<< FAILURE!
2024-05-14T09:58:11.0018271Z java.lang.AssertionError
2024-05-14T09:58:11.0018820Z 	at org.junit.Assert.fail(Assert.java:87)
2024-05-14T09:58:11.0019521Z 	at org.junit.Assert.assertTrue(Assert.java:42)
2024-05-14T09:58:11.0020257Z 	at org.junit.Assert.assertTrue(Assert.java:53)
2024-05-14T09:58:11.0021655Z 	at org.geotools.data.shapefile.ShapefileDataStoreTest.testIgnoreIndexStaleness(ShapefileDataStoreTest.java:2107)