GH-5631 Deprecate solr integration and update documentation (#5632)

hmottestad · web-flow · commit 8b727920028e · 2025-12-20T21:31:17.000+01:00
diff --git a/core/sail/solr/pom.xml b/core/sail/solr/pom.xml
@@ -8,7 +8,7 @@
 	</parent>
 	<artifactId>rdf4j-sail-solr</artifactId>
 	<name>RDF4J: Solr Sail Index</name>
-	<description>StackableSail implementation offering full-text search on literals, based on Solr.</description>
+	<description>StackableSail implementation offering full-text search on literals, based on Solr. Deprecated for removal.</description>
 	<properties>
 		<!-- FIXME: Support for embedded Solr server require non-provided Java EE dependencies -->
 		<enforce-javaee-provided.fail>false</enforce-javaee-provided.fail>
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrBulkUpdater.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrBulkUpdater.java
@@ -21,6 +21,11 @@
 import org.eclipse.rdf4j.sail.lucene.BulkUpdater;
 import org.eclipse.rdf4j.sail.lucene.SearchDocument;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrBulkUpdater implements BulkUpdater {
 
 	private final SolrClient client;
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrClientFactory.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrClientFactory.java
@@ -12,6 +12,11 @@
 
 import org.apache.solr.client.solrj.SolrClient;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public interface SolrClientFactory {
 
 	SolrClient create(String spec);
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrDocumentDistance.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrDocumentDistance.java
@@ -14,6 +14,11 @@
 import org.eclipse.rdf4j.sail.lucene.DocumentDistance;
 import org.eclipse.rdf4j.sail.lucene.util.GeoUnits;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrDocumentDistance extends SolrDocumentResult implements DocumentDistance {
 
 	private final IRI units;
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrDocumentResult.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrDocumentResult.java
@@ -13,6 +13,11 @@
 import org.eclipse.rdf4j.sail.lucene.DocumentResult;
 import org.eclipse.rdf4j.sail.lucene.SearchDocument;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrDocumentResult implements DocumentResult {
 
 	protected final SolrSearchDocument doc;
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrDocumentScore.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrDocumentScore.java
@@ -15,6 +15,11 @@
 
 import org.eclipse.rdf4j.sail.lucene.DocumentScore;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrDocumentScore extends SolrDocumentResult implements DocumentScore {
 
 	private final Map<String, List<String>> highlighting;
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrIndex.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrIndex.java
@@ -59,7 +59,10 @@
 
 /**
  * @see LuceneSail
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
  */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrIndex extends AbstractSearchIndex {
 
 	public static final String SERVER_KEY = "server";
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrSearchDocument.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrSearchDocument.java
@@ -20,6 +20,11 @@
 import org.eclipse.rdf4j.sail.lucene.SearchDocument;
 import org.eclipse.rdf4j.sail.lucene.SearchFields;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrSearchDocument implements SearchDocument {
 
 	private final SolrDocument doc;
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrSearchQuery.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrSearchQuery.java
@@ -29,8 +29,11 @@
 
 /**
  * To be removed, no longer used.
+ *
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
  */
-@Deprecated
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrSearchQuery implements SearchQuery {
 
 	private final SolrQuery query;
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrUtil.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/SolrUtil.java
@@ -14,8 +14,12 @@
 import org.apache.solr.common.SolrInputDocument;
 
 /**
- * Utility for Solr handling
+ * Utility for Solr handling.
+ *
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
  */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrUtil {
 
 	/**
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/client/cloud/Factory.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/client/cloud/Factory.java
@@ -18,6 +18,11 @@
 
 import com.google.common.collect.Lists;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class Factory implements SolrClientFactory {
 
 	@Override
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/client/embedded/Factory.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/client/embedded/Factory.java
@@ -19,6 +19,11 @@
 import org.apache.solr.core.SolrXmlConfig;
 import org.eclipse.rdf4j.sail.solr.SolrClientFactory;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class Factory implements SolrClientFactory {
 
 	@Override
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/client/http/Factory.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/client/http/Factory.java
@@ -14,6 +14,11 @@
 import org.apache.solr.client.solrj.impl.HttpSolrClient;
 import org.eclipse.rdf4j.sail.solr.SolrClientFactory;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class Factory implements SolrClientFactory {
 
 	@Override
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/config/SolrSailConfig.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/config/SolrSailConfig.java
@@ -13,6 +13,11 @@
 import org.eclipse.rdf4j.sail.config.SailImplConfig;
 import org.eclipse.rdf4j.sail.lucene.config.AbstractLuceneSailConfig;
 
+/**
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
+ */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrSailConfig extends AbstractLuceneSailConfig {
 
 	/*--------------*
diff --git a/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/config/SolrSailFactory.java b/core/sail/solr/src/main/java/org/eclipse/rdf4j/sail/solr/config/SolrSailFactory.java
@@ -20,7 +20,11 @@
 
 /**
  * A {@link SailFactory} that creates {@link LuceneSail}s based on RDF configuration data.
+ *
+ * @deprecated since 5.3.0. Solr integration is deprecated for removal; use alternative Lucene-backed search
+ *             implementations instead.
  */
+@Deprecated(since = "5.3.0", forRemoval = true)
 public class SolrSailFactory implements SailFactory {
 
 	/**
diff --git a/core/sail/solr/src/test/java/org/eclipse/rdf4j/sail/solr/SolrSailDeprecationTest.java b/core/sail/solr/src/test/java/org/eclipse/rdf4j/sail/solr/SolrSailDeprecationTest.java
@@ -0,0 +1,54 @@
+/*******************************************************************************
+ * Copyright (c) 2025 Eclipse RDF4J contributors.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Distribution License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *******************************************************************************/
+// Some portions generated by Codex
+package org.eclipse.rdf4j.sail.solr;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.lang.reflect.Modifier;
+import java.util.List;
+import java.util.stream.Collectors;
+
+import org.eclipse.rdf4j.sail.solr.config.SolrSailConfig;
+import org.eclipse.rdf4j.sail.solr.config.SolrSailFactory;
+import org.junit.jupiter.api.Test;
+
+class SolrSailDeprecationTest {
+
+	private static final List<Class<?>> SOLR_CLASSES = List.of(
+			SolrBulkUpdater.class, SolrClientFactory.class, SolrDocumentDistance.class, SolrDocumentResult.class,
+			SolrDocumentScore.class, SolrIndex.class, SolrSearchDocument.class, SolrSearchQuery.class, SolrUtil.class,
+			SolrSailConfig.class, SolrSailFactory.class,
+			org.eclipse.rdf4j.sail.solr.client.cloud.Factory.class,
+			org.eclipse.rdf4j.sail.solr.client.http.Factory.class,
+			org.eclipse.rdf4j.sail.solr.client.embedded.Factory.class);
+
+	@Test
+	void allSolrClassesAreDeprecatedForRemovalOrNonPublic() {
+		List<String> violations = SOLR_CLASSES.stream()
+				.filter(SolrSailDeprecationTest::isPublicAndNotDeprecatedForRemoval)
+				.map(Class::getName)
+				.collect(Collectors.toList());
+
+		assertTrue(violations.isEmpty(),
+				"Expected all Solr classes to be deprecated for removal or non-public, but found: " + violations);
+	}
+
+	private static boolean isPublicAndNotDeprecatedForRemoval(Class<?> clazz) {
+		int modifiers = clazz.getModifiers();
+		if (!Modifier.isPublic(modifiers)) {
+			return false;
+		}
+
+		Deprecated deprecated = clazz.getAnnotation(Deprecated.class);
+		return deprecated == null || !deprecated.forRemoval();
+	}
+}
diff --git a/site/content/documentation/programming/geosparql.md b/site/content/documentation/programming/geosparql.md
@@ -72,7 +72,7 @@ RDF4J supports the following RCC8 functions: `geof:rcc8eq`, `geof:rcc8dc`, `geof
 
 ### Improved performance through Lucene
 
-Although RDF4J supports GeoSPARQL querying on any type of store, the Lucene SAIL and its derivates (the SolrSail and the ElasticSearchSail) have built-in optimizations that make geospatial querying on large datasets more efficient. By default, the Lucene SAIL only spatially indexes `http://www.opengis.net/ont/geosparql#asWKT fields`. This can be changed using the `LuceneSail.WKT_FIELDS` parameter.
+Although RDF4J supports GeoSPARQL querying on any type of store, the Lucene SAIL and its derivates (the SolrSail and the ElasticSearchSail) have built-in optimizations that make geospatial querying on large datasets more efficient. The SolrSail integration is deprecated for removal as of RDF4J 5.3.0; prefer the Lucene or Elasticsearch variants instead. By default, the Lucene SAIL only spatially indexes `http://www.opengis.net/ont/geosparql#asWKT fields`. This can be changed using the `LuceneSail.WKT_FIELDS` parameter.
 
 ## Reading and writing WKT Literals
 
@@ -85,4 +85,3 @@ Here are some useful links:
 - [Spatial4J website](https://projects.eclipse.org/projects/locationtech.spatial4j)
 - [OGC GeoSPARQL specification](http://www.opengeospatial.org/standards/geosparql)
 - [Wikipedia article on WKT](https://en.wikipedia.org/wiki/Well-known_text)
-
diff --git a/site/content/documentation/programming/lucene.md b/site/content/documentation/programming/lucene.md
@@ -182,11 +182,18 @@ The LuceneSail can currently be used with three SearchIndex implementations:
 |------------------ |-----------------------------------------------------------|---------------------------------------|-------------------------|
 | Apache Lucene     | `org.eclipse.rdf4j.sail.lucene.impl.LuceneIndex`          | `rdf4j-sail-lucene`                   | yes                      |
 | ElasticSearch     | `org.eclipse.rdf4j.sail.elasticsearch.ElasticsearchIndex` | `rdf4j-sail-elasticsearch`            | no                      |
-| Apache Solr       | `org.eclipse.rdf4j.sail.solr.SolrIndex`                   | `rdf4j-sail-solr`                     | no                      |
+| Apache Solr       | `org.eclipse.rdf4j.sail.solr.SolrIndex`                   | `rdf4j-sail-solr` (deprecated for removal) | no                      |
+
+> **Warning**
+> The Solr-based SearchIndex (`rdf4j-sail-solr`) is deprecated for removal as of RDF4J 5.3.0. Prefer the Lucene
+> and Elasticsearch integrations instead.
 
 Each SearchIndex implementation can easily be extended if you need to add extra features or store/access data with a different schema.
 
-The following example uses a local Solr instance running on the default port 8983. Make sure that both the Apache httpcore and commons-logging jars are in the classpath, and that the Solr core uses an appropriate schema (an example can be found in RDF4J’s embedded solr source code on GitHub).
+The following example uses a local Solr instance running on the default port 8983. Solr support is deprecated for
+removal; the example is provided for existing deployments only. Make sure that both the Apache httpcore and
+commons-logging jars are in the classpath, and that the Solr core uses an appropriate schema (an example can be found
+in RDF4J’s embedded solr source code on GitHub).
 
 ```java
 import org.eclipse.rdf4j.sail.solr.SolrIndex;
@@ -202,4 +209,3 @@ If needed, the Solr Client can be accessed via:
 SolrIndex index = (SolrIndex) luceneSail.getLuceneIndex();
 SolrClient client = index.getClient();
 ```
-
