HSEARCH-903 Cleaning up the javadocs for IndexReaderAccessor

Refactored DirectorySelectionTest and added some more test. Moving some IllegalArgumentException creation into Log

hibernate-search/src/main/java/org/hibernate/search/backend/impl/lucene/AbstractWorkspaceImpl.java

@@ -107,7 +107,7 @@ public Set<Class<?>> getEntitiesInIndexManager() {
 	public abstract void afterTransactionApplied(boolean someFailureHappened);
 
 	public void shutDownNow() {
-		log.shuttindDownBackend( indexManager.getIndexName() );
+		log.shuttingDownBackend( indexManager.getIndexName() );
 		writerHolder.closeIndexWriter();
 	}
 

hibernate-search/src/main/java/org/hibernate/search/impl/DefaultIndexReaderAccessor.java

@@ -20,10 +20,12 @@
  */
 package org.hibernate.search.impl;
 
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.TreeSet;
 
 import org.apache.lucene.index.IndexReader;
+
 import org.hibernate.search.engine.spi.EntityIndexBinder;
 import org.hibernate.search.indexes.IndexReaderAccessor;
 import org.hibernate.search.indexes.impl.IndexManagerHolder;
@@ -35,7 +37,7 @@
 /**
  * Provides access to IndexReaders.
  * IndexReaders opened through this service need to be closed using this service.
- * 
+ *
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.
  */
 public class DefaultIndexReaderAccessor implements IndexReaderAccessor {
@@ -71,13 +73,8 @@ public IndexReader open(Class<?>... entities) {
 	@Override
 	public IndexReader open(String... indexNames) {
 		TreeSet<String> names = new TreeSet<String>();
-		for ( String indexName : indexNames ) {
-			names.add( indexName );
-		}
+		Collections.addAll( names, indexNames );
 		final int size = names.size();
-		if ( size == 0 ) {
-			throw log.needAtLeastOneIndexName();
-		}
 		String[] indexManagerNames = names.toArray( new String[size] );
 		IndexManagerHolder managerSource = searchFactory.getAllIndexesManager();
 		IndexManager[] managers = new IndexManager[size];
@@ -90,5 +87,4 @@ public IndexReader open(String... indexNames) {
 		}
 		return MultiReaderFactory.openReader( managers );
 	}
-
 }

hibernate-search/src/main/java/org/hibernate/search/impl/ImmutableSearchFactory.java

@@ -327,13 +327,13 @@ public IndexManagerHolder getAllIndexesManager() {
 		return this.allIndexesManager;
 	}
 
-	EntityIndexBinder getSafeIndexBindingForEntity(Class entityType) {
+	EntityIndexBinder getSafeIndexBindingForEntity(Class<?> entityType) {
 		if ( entityType == null ) {
-			throw new IllegalArgumentException( "Null is not a valid indexed entity type" );
+			throw log.nullIsInvalidIndexedType();
 		}
 		EntityIndexBinder entityIndexBinding = getIndexBindingForEntity( entityType );
 		if ( entityIndexBinding == null ) {
-			throw new IllegalArgumentException( "Entity is not an indexed type: " + entityType );
+			throw log.notAnIndexedType( entityType.getName() );
 		}
 		return entityIndexBinding;
 	}
@@ -347,5 +347,4 @@ public ErrorHandler getErrorHandler() {
 	public IndexReaderAccessor getIndexReaderAccessor() {
 		return indexReaderAccessor;
 	}
-
 }

hibernate-search/src/main/java/org/hibernate/search/indexes/IndexReaderAccessor.java

@@ -23,12 +23,15 @@
 import org.apache.lucene.index.IndexReader;
 
 /**
- * The ReaderAccessor exposes the IndexReaders directly, making it possible to query the Lucene
- * indexes directly bypassing the helpers provided by Hibernate Search.
- * This API is intended for power users intending to extract information directly.
- *
- * The returned IndexReader instances are always read-only, and it's expected that they are closed
+ * The {@code IndexReaderAccessor} exposes {@link IndexReader}s directly, making it possible to query the Lucene
+ * indexes directly bypassing Hibernate Search.
+ * <p>
+ * The returned IndexReader instances are always read-only and must be closed
  * using the {@link #close(IndexReader)} method on this same instance.
+ * </p>
+ * <P>
+ * <b>Note:</b> this API is intended for power users intending to extract information directly.
+ * </p>
  *
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.
  */
@@ -41,13 +44,21 @@ public interface IndexReaderAccessor {
 	 * the single IndexReader will act as a MultiReader on the aggregate of these indexes.
 	 * This MultiReader is not filtered by Hibernate Search, so it might contain information
 	 * relevant to different types as well.
-	 * <p>The returned IndexReader is read only; writing directly to the index is discouraged, in need use the
-	 * {@link org.hibernate.search.spi.SearchFactoryIntegrator#getWorker()} to queue change operations to the backend.</p>
-	 * <p>The IndexReader should not be closed in other ways, but must be returned to this instance to
-	 * {@link #close(IndexReader)}.</p>
-	 * 
-	 * @param entities
+	 * <p>
+	 * The returned IndexReader is read only; writing directly to the index is discouraged. If you
+	 * need to write to the index use the
+	 * {@link org.hibernate.search.spi.SearchFactoryIntegrator#getWorker()} to queue change operations to the backend.
+	 * </p>
+	 * <p>
+	 * The IndexReader should not be closed in other ways except being returned to this instance via
+	 * {@link #close(IndexReader)}.
+	 * </p>
+	 *
+	 * @param entities the entity types for which to return a (multi)reader
+	 *
 	 * @return an IndexReader containing at least all listed entities
+	 *
+	 * @throws IllegalArgumentException if one of the specified classes is not indexed
 	 */
 	IndexReader open(Class<?>... entities);
 
@@ -56,16 +67,19 @@ public interface IndexReaderAccessor {
 	 * A single name can be provided, or multiple. In the case of multiple names it
 	 * still returns a single IndexReader instance, but this will make it possible to run
 	 * queries on the combination of each index.
+	 *
 	 * @param indexNames At least one IndexManager name.
+	 *
 	 * @return an IndexReader instance.
-	 * @throws SearchException for unstarted indexManager names which fail to start, or for an empty parameter list.
+	 *
+	 * @throws org.hibernate.search.SearchException if the index manager to which the named index belongs failed to start
 	 */
 	IndexReader open(String... indexNames);
 
 	/**
 	 * Closes IndexReader instances obtained using {@link #open(Class...)}
+	 *
 	 * @param indexReader the IndexReader to be closed
 	 */
 	void close(IndexReader indexReader);
-
 }

hibernate-search/src/main/java/org/hibernate/search/util/logging/impl/Log.java

@@ -22,10 +22,6 @@
  */
 package org.hibernate.search.util.logging.impl;
 
-import static org.jboss.logging.Logger.Level.ERROR;
-import static org.jboss.logging.Logger.Level.INFO;
-import static org.jboss.logging.Logger.Level.WARN;
-
 import java.io.File;
 import java.io.IOException;
 import java.util.Properties;
@@ -40,8 +36,12 @@
 
 import org.hibernate.search.SearchException;
 
+import static org.jboss.logging.Logger.Level.ERROR;
+import static org.jboss.logging.Logger.Level.INFO;
+import static org.jboss.logging.Logger.Level.WARN;
+
 /**
- * Hibernate Search's log abstraction layer on top of JBoss Logging.
+ * Log abstraction layer for Hibernate Search on top of JBoss Logging.
  *
  * @author Davide D'Alto
  * @since 4.0
@@ -383,7 +383,8 @@ public interface Log extends BasicLogger {
 	void messageReceivedForUndefinedIndex(String indexName);
 
 	@LogMessage(level = WARN)
-	@Message(id = 81, value = "The index '%1$s' is using a non-recommended combination of backend and directoryProvider implementations")
+	@Message(id = 81,
+			value = "The index '%1$s' is using a non-recommended combination of backend and directoryProvider implementations")
 	void warnSuspiciousBackendDirectoryCombination(String indexName);
 
 	@Message(id = 82, value = "Unable to start serialization layer")
@@ -422,7 +423,8 @@ public interface Log extends BasicLogger {
 	@Message(id = 93, value = "Unknown Field type: %1$s")
 	SearchException unknownFieldType(Class<?> fieldType);
 
-	@Message(id = 94, value = "Cannot serialize custom Fieldable '%1$s'. Must be NumericField, Field or a Serializable Fieldable implementation.")
+	@Message(id = 94,
+			value = "Cannot serialize custom Fieldable '%1$s'. Must be NumericField, Field or a Serializable Fieldable implementation.")
 	SearchException cannotSerializeCustomField(Class<?> fieldType);
 
 	@Message(id = 95, value = "Fail to serialize object of type %1$s")
@@ -435,7 +437,7 @@ public interface Log extends BasicLogger {
 	SearchException unableToReadFile(String filename, @Cause Throwable e);
 
 	@Message(id = 98, value = "Unable to parse message from protocol version %1$d.%2$d. "
-							+ "Current protocol version: %3$d.%4$d")
+			+ "Current protocol version: %3$d.%4$d")
 	SearchException incompatibleProtocolVersion(int messageMajor, int messageMinor, int currentMajor, int currentMinor);
 
 	@Message(id = 99, value = "Unable to deserialize Avro stream")
@@ -468,10 +470,13 @@ public interface Log extends BasicLogger {
 	@Message(id = 107, value = "Index names %1$s is not defined")
 	SearchException requestedIndexNotDefined(String indexName);
 
-	@Message(id = 108, value = "At least one index name should be provided: can't open an IndexReader on nothing")
-	SearchException needAtLeastOneIndexName();
-
 	@LogMessage(level = Level.DEBUG)
-	@Message(id = 109, value = "Shutting down backend for IndexManager '%1$s'")
-	void shuttindDownBackend(String indexName);
+	@Message(id = 108, value = "Shutting down backend for IndexManager '%1$s'")
+	void shuttingDownBackend(String indexName);
+
+	@Message(id = 109, value = "%1$s is not an indexed type")
+	IllegalArgumentException notAnIndexedType(String entityName);
+
+	@Message(id = 110, value = "'null' is not a valid indexed type")
+	IllegalArgumentException nullIsInvalidIndexedType();
 }

hibernate-search/src/test/java/org/hibernate/search/test/shards/DirectorySelectionTest.java

@@ -21,8 +21,8 @@
 package org.hibernate.search.test.shards;
 
 import junit.framework.Assert;
-
 import org.apache.lucene.index.IndexReader;
+
 import org.hibernate.Session;
 import org.hibernate.Transaction;
 import org.hibernate.cfg.Configuration;
@@ -38,66 +38,92 @@
  * @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.
  */
 public class DirectorySelectionTest extends SearchTestCase {
+	private IndexReaderAccessor indexReaderAccessor;
 
-	public void testDirectoryProviderForQuery() throws Exception {
-
-		Session s = openSession( );
-		Transaction tx = s.beginTransaction();
-
-		Product p1 = new Product();
-		p1.setName( "The Definitive ANTLR Reference: Building Domain-Specific Languages" );
-		p1.setAvailable( true );
-		s.persist( p1 );
-
-		Product p2 = new Product();
-		p2.setName( "Recipes for distributed cloud applications using Infinispan" );
-		p2.setAvailable( false );
-		s.persist( p2 );
-
-		tx.commit();
-
-		s.clear();
-
-		FullTextSession fts = Search.getFullTextSession( s );
-		IndexReaderAccessor indexReaders = fts.getSearchFactory().getIndexReaderAccessor();
-		fts.close();
+	public void setUp() throws Exception {
+		super.setUp();
+		FullTextSession fts = indexData();
+		indexReaderAccessor = fts.getSearchFactory().getIndexReaderAccessor();
+	}
 
-		IndexReader indexReader = indexReaders.open( Product.class );
+	public void testDirectoryProviderForQuery() throws Exception {
+		IndexReader indexReader = indexReaderAccessor.open( Product.class );
 		try {
 			Assert.assertEquals( 2, indexReader.numDocs() );
 		}
 		finally {
-			indexReaders.close( indexReader );
+			indexReaderAccessor.close( indexReader );
 		}
 
-		indexReader = indexReaders.open( "Products.0" );
+		indexReader = indexReaderAccessor.open( "Products.0" );
 		try {
 			Assert.assertEquals( 1, indexReader.numDocs() );
 		}
 		finally {
-			indexReaders.close( indexReader );
+			indexReaderAccessor.close( indexReader );
 		}
 
-		indexReader = indexReaders.open( "Products.1" );
+		indexReader = indexReaderAccessor.open( "Products.1" );
 		try {
 			Assert.assertEquals( 1, indexReader.numDocs() );
 		}
 		finally {
-			indexReaders.close( indexReader );
+			indexReaderAccessor.close( indexReader );
 		}
+	}
 
+	public void testOpeningIndexReaderByUnknownNameThrowsException() throws Exception {
 		try {
-			indexReader = indexReaders.open( "Products.1", "hoa?" );
+			indexReaderAccessor.open( "Products.1", "hoa?" );
 			Assert.fail( "should have failed" );
 		}
-		catch (SearchException se) {
+		catch ( SearchException se ) {
 			Assert.assertEquals( "HSEARCH000107: Index names hoa? is not defined", se.getMessage() );
 		}
 	}
 
+	public void testOpeningIndexReaderByUnknownEntityThrowsException() throws Exception {
+		try {
+			indexReaderAccessor.open( this.getClass() );
+			Assert.fail( "should have failed" );
+		}
+		catch ( IllegalArgumentException e ) {
+			Assert.assertEquals(
+					"HSEARCH000109: org.hibernate.search.test.shards.DirectorySelectionTest is not an indexed type",
+					e.getMessage()
+			);
+		}
+	}
+
+	private FullTextSession indexData() {
+		Session s = openSession();
+		Transaction tx = s.beginTransaction();
+
+		Product p1 = new Product();
+		p1.setName( "The Definitive ANTLR Reference: Building Domain-Specific Languages" );
+		p1.setAvailable( true );
+		s.persist( p1 );
+
+		Product p2 = new Product();
+		p2.setName( "Recipes for distributed cloud applications using Infinispan" );
+		p2.setAvailable( false );
+		s.persist( p2 );
+
+		tx.commit();
+
+		s.clear();
+
+		FullTextSession fts = Search.getFullTextSession( s );
+		fts.close();
+		return fts;
+	}
+
 	protected void configure(Configuration cfg) {
 		super.configure( cfg );
-		cfg.setProperty( "hibernate.search.Products.sharding_strategy", ProductsAvailabilityShardingStrategy.class.getCanonicalName() );
+		cfg.setProperty(
+				"hibernate.search.Products.sharding_strategy",
+				ProductsAvailabilityShardingStrategy.class.getCanonicalName()
+		);
 		cfg.setProperty( "hibernate.search.Products.sharding_strategy.nbr_of_shards", "2" );
 	}
 
@@ -107,5 +133,4 @@ protected Class<?>[] getAnnotatedClasses() {
 				Product.class
 		};
 	}
-
 }