CCM NG/ccm-cms : Support for Hibernate Search queries for content items

CCM NG/ccm-core: JavaDoc for the SearchManager 


git-svn-id: https://svn.libreccm.org/ccm/ccm_ng@4489 8810af33-2d31-482b-a856-94f89814c4df

ccm-cms/pom.xml

@@ -65,6 +65,12 @@
             <scope>provided</scope>
         </dependency>
         
+        <dependency>
+            <groupId>org.hibernate</groupId>
+            <artifactId>hibernate-search-orm</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>

ccm-cms/src/main/java/org/librecms/contentsection/ContentItemSearchManager.java

@@ -0,0 +1,119 @@
+/*
+ * Copyright (C) 2016 LibreCCM Foundation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301  USA
+ */
+package org.librecms.contentsection;
+
+import org.apache.lucene.search.Query;
+import org.hibernate.search.query.dsl.QueryBuilder;
+import org.libreccm.search.SearchManager;
+
+import java.util.List;
+
+import javax.enterprise.context.RequestScoped;
+import javax.inject.Inject;
+
+/**
+ * Provides search queries (using Hibernate Search and Lucene) for ContentItems.
+ * For details about the different search methods ({@code match}, {@code fuzzy}
+ * and {@code wildcard} please refer to chapter 5 of the
+ * <a href="https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_single/#search-query">Hibernate
+ * Search documentation</a>.
+ *
+ * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
+ */
+@RequestScoped
+public class ContentItemSearchManager {
+
+    /**
+     * The fields in which the search engine looks for the provided term.
+     */
+    private static final String[] FIELDS = {"id",
+                                            "uuid",
+                                            "displayName",
+                                            "title",
+                                            "description"};
+
+    @Inject
+    private SearchManager searchManager;
+
+    /**
+     * Create and execute a {@code match} query.
+     *
+     * @param term The term(s) to search for.
+     *
+     * @return A list containing all results matching the query.
+     */
+    @SuppressWarnings("unchecked")
+    public List<ContentItem> searchItemMatch(final String term) {
+        final QueryBuilder queryBuilder = searchManager.createQueryBuilder(
+            ContentItem.class);
+
+        final Query luceneQuery = queryBuilder
+            .keyword()
+            .onFields(FIELDS)
+            .matching(term)
+            .createQuery();
+
+        return (List<ContentItem>) searchManager.executeQuery(luceneQuery);
+    }
+
+    /**
+     * Create and execute a {@code fuzzy} query.
+     *
+     * @param term The term(s) to search for.
+     *
+     * @return A list containing all results matching the query.
+     */
+    @SuppressWarnings("unchecked")
+    public List<ContentItem> searchItemFuzzy(final String term) {
+        final QueryBuilder queryBuilder = searchManager.createQueryBuilder(
+            ContentItem.class);
+
+        final Query luceneQuery = queryBuilder
+            .keyword()
+            .fuzzy()
+            .onFields(FIELDS)
+            .matching(term)
+            .createQuery();
+
+        return (List<ContentItem>) searchManager.executeQuery(luceneQuery);
+    }
+
+    /**
+     * Create and execute a {@code wildcard} query.
+     *
+     * @param term The term(s) to search for.
+     *
+     * @return A list containing all results matching the query.
+     */
+    @SuppressWarnings("unchecked")
+    public List<ContentItem> searchItemWildcard(final String term) {
+        final QueryBuilder queryBuilder = searchManager.createQueryBuilder(
+            ContentItem.class);
+
+        final Query luceneQuery = queryBuilder
+            .keyword()
+            .wildcard()
+            .onFields(FIELDS)
+            .matching(term)
+            .createQuery();
+
+        return (List<ContentItem>) searchManager.executeQuery(luceneQuery);
+    }
+
+}

ccm-core/src/main/java/org/libreccm/search/SearchManager.java

@@ -38,6 +38,8 @@ import javax.persistence.EntityManager;
 import javax.transaction.Transactional;
 
 /**
+ * Provides an interface to Hibernate search. The methods here can be used to
+ * reduce the boilerplate code for writing Hibernate Search queries.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -49,15 +51,21 @@ public class SearchManager {
 
     private FullTextEntityManager fullTextEntityManager;
 
-    public SearchManager() {
+    /**
-        
+     * Initialises the class by creating a {@link FullTextEntityManager}.
-    }
+     */
-    
     @PostConstruct
     private void init() {
         fullTextEntityManager = Search.getFullTextEntityManager(entityManager);
     }
 
+    /**
+     * Rebuild the complete index. This methods requires {@code admin}
+     * privileges.
+     *
+     * @return A {@link Future} object for controlling/monitoring the index
+     *         process.
+     */
     @AuthorizationRequired
     @RequiresPrivilege(CoreConstants.PRIVILEGE_ADMIN)
     public Future<?> rebuildIndex() {
@@ -65,11 +73,30 @@ public class SearchManager {
         return indexer.start();
     }
 
+    /**
+     * Creates a {@link QueryBuilder} for the provided entity class.
+     *
+     * @param entityClass The entity class.
+     *
+     * @return A {@link QueryBuilder} which can be used to create a Hibernate
+     *         Search/Lucene query for entities of the provided class.
+     */
     public QueryBuilder createQueryBuilder(final Class<?> entityClass) {
-        final SearchFactory searchFactory = fullTextEntityManager.getSearchFactory();
+        final SearchFactory searchFactory = fullTextEntityManager
+            .getSearchFactory();
         return searchFactory.buildQueryBuilder().forEntity(entityClass).get();
     }
 
+    /**
+     * Executes a Hibernate Search/Lucene query. This method contains uses the
+     * {@link #fullTextEntityManager} to wrap the Lucene query into an
+     * Hibernate/JPA query. To avoid lazy loading issues this method is
+     * transactional.
+     *
+     * @param query The query to execute.
+     *
+     * @return A result list containing all entities matching the query.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public List<?> executeQuery(final Query query) {
         final javax.persistence.Query jpaQuery = fullTextEntityManager