chore: refactor indexing to prepare for Neighborhoods

[triceo]

This PR has two commits, which will be merged separately and I suggest they be reviewed separately as well. (I should have probably just made them two different PRs, but alas.)

First commit introduces a new collection that will serve as indexing backend for Neighborhoods. It is on average 10 - 15 % slower than the CS indexing backend, but gives us the power of direct access. This is a worthwhile trade-off, because Neighborhoods will need to access elements of the index randomly, and that would require copying the linked list to an array list, killing performance entirely.

Second commit renames "indexKeys" to "compositeKey" - this is a very straightforward name, and I have no idea why we were using the confusing name "indexKeys" until now. It's a composite key, let's call it that. It also does other small refactorings, as I was already there.

Microbenchmarks did not detect any regression, as expected; there are no actual runtime changes here.

[Copilot]

Pull request overview

This PR refactors the indexing infrastructure to prepare for the Neighborhoods feature. The main changes include introducing a new ElementAwareArrayList collection that supports random access (at the cost of 10-15% slower performance compared to the linked list variant), and renaming IndexKeys to CompositeKey throughout the codebase for better clarity.

• Introduced ElementAwareArrayList as a new indexing backend with random access support
• Created ListEntry interface to unify entry types across different list implementations
• Renamed IndexKeys to CompositeKey for improved code clarity
• Renamed ElementAwareList to ElementAwareLinkedList for consistency
• Introduced IndexerBackend interface to support multiple backend implementations

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
ElementAwareArrayList.java	New array-backed list with gap-tolerant removal and lazy compaction
ElementAwareLinkedList.java	Renamed from ElementAwareList, with Entry class moved inside
ListEntry.java	New common interface for list entries
IndexerBackend.java	New sealed interface for indexer backends
RandomAccessIndexerBackend.java	New indexer backend using ElementAwareArrayList
LinkedListIndexerBackend.java	Renamed from NoneIndexer, uses ElementAwareLinkedList
CompositeKey.java	Renamed from IndexKeys with updated documentation
BiCompositeKey.java	Renamed from TwoIndexKeys
MegaCompositeKey.java	Renamed from ManyIndexKeys
CompositeKeyRetriever.java	Renamed from ManyKeyRetriever
EqualsIndexer.java	Updated to use CompositeKey terminology and added asList support
ComparisonIndexer.java	Updated to use CompositeKey terminology and added asList support
Indexer.java	Updated interface with CompositeKey terminology and new asList method
IndexerFactory.java	Updated to use CompositeKey and LinkedListIndexerBackend
All test files	Updated to use new naming conventions

Comments suppressed due to low confidence (1)

core/src/main/java/ai/timefold/solver/core/impl/util/ElementAwareLinkedList.java:333

• This method overrides ListEntry.getElement; it is advisable to add an Override annotation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
79.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud