HSEARCH-1430 Document ShardIdentifierProvider is experimental

hibernate · Oct 8, 2013 · 929380d · 929380d
1 parent 4ccf8eb
commit 929380d
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 1 deletion.
diff --git a/documentation/src/main/docbook/en-US/modules/advanced-features.xml b/documentation/src/main/docbook/en-US/modules/advanced-features.xml
@@ -281,6 +281,13 @@ finally {
       query (<classname>getShardIdentifiersForQuery()</classname>, not shown
       in the example) and thus speed up the query execution.</para>
     </section>
+    <important>
+        <para>This <classname>ShardIdentifierProvider</classname> is considered
+        experimental. We might need to apply some changes to the defined method
+        signatures to accomodate for unforeseen use cases. Please provide
+        feedback if you have ideas, or just to let us know how you're using
+        this API.</para>
+    </important>
   </section>
 
   <section id="section-sharing-indexes">

diff --git a/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProvider.java b/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProvider.java
@@ -41,6 +41,8 @@
  * Instead of implementing this interface directly, implementations should be derived from
  * {@link ShardIdentifierProviderTemplate} as new methods might be added to this interface in future releases.
  *
+ * @experimental The exact method signatures are likely to change in future.
+ *
  * @author Emmanuel Bernard <emmanuel@hibernate.org>
  * @author Hardy Ferentschik
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2013 Red Hat Inc.
@@ -100,7 +102,7 @@ public interface ShardIdentifierProvider {
 	 * {@link #getShardIdentifier(Class, Serializable, String, Document)}, {@link #getShardIdentifiersForQuery(FullTextFilterImplementor[])},
 	 * {@link #getAllShardIdentifiers()}.
 	 *
-	 * @return the list of all currently known shard identifiers.
+	 * @return the set of all currently known shard identifiers.
 	 */
 	Set<String> getAllShardIdentifiers();
 }
diff --git a/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProviderTemplate.java b/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProviderTemplate.java
@@ -32,6 +32,8 @@
  * Recommended parent class to create custom {@link ShardIdentifierProvider} implementations. Sub-classes must provide a
  * no-arg constructor.
  *
+ * @experimental The exact method signatures are likely to change in future.
+ *
  * @author Sanne Grinovero
  */
 public abstract class ShardIdentifierProviderTemplate implements ShardIdentifierProvider {