Jiří Hradil blog

Pokud chceme do naší Java aplikace integrovat fulltextové vyhledávání, dříve či později skončíme u Apache Lucene, frameworku, který je pro vyhledávání v Javě v podstatě standardem a synonymem. Pokud se rozhodneme používat čistý Lucene, musíme mj. řešit:

• mapování doménových objektů do Lucene (v Lucene jsou všechny atributy obyčejné řetězce)
• mapování výsledků vyhledávání zpátky do doménových objektů
• transakce
• otevírání a zavírání indexu
• zamykání indexu, v 1 okamžiku může do indexu zapisovat pouze 1 proces
• škálování fulltextu přes více serverů

Jestliže se však držíme zavedených řešení a používáme Hibernate (ať už Hibernate Core nebo Hibernate jako JPA providera), můžeme využít rozšíření Hibernate Search.
Hibernate Search je projekt, který Hibernate Core doplňuje o fulltextové prohledávání persistovaných objektů a funguje jako fasáda nad Lucene.

Hibernate Search nabízí:

• API nad fulltextem podobné JPA
• odstínění od low-level objektů Lucene-nestaráme se vůbec o otevření/uzavření indexu, o zamykání indexu 1 procesem, atd.
• fulltextové vyhledávání nad persistovanými objekty pomocí Lucene tříd a objektů
• automatický převod objektů do indexu a zpět (pokud nevyhovuje/nepostačuje, lze napsat převodníky)
• automatickou synchronizaci indexu s doménovými objekty
• reindexaci již persistovaných objektů
• výsledky vyhledávání jsou kompletní objekty, Hibernate Search vrátí na dotaz seznam vyhovujících ID a Hibernate pak načte z db objekty s těmito ID
• transakční chování – zápis do fulltext indexu se provádí až nakonec po commitu změn do db
• škálování jako master/slave pomocí JMS
• jednoduchost, pokud známe Lucene a Hibernate, můžeme jej začít používat okamžitě.

Ukázková aplikace

Pro praktickou ukázku integrujeme fulltextové vyhledávání do jednoduché webové aplikace pro správu firem (klasická create-read-update aplikace).

Použitý stack

• Hibernate Entity Manager 3.4.0.GA - persistence
• Hibernate Search 3.1.0.GA – fulltext
• Apache Maven 2.0.9 – project management
• Apache Wicket 1.3.5 – prezentační vrstva
• Spring 2.5.5 – lepidlo
• PostgreSQL 8.2-relační databáze

Poznámka k následujícím zdrojovým kódům: uvádím pouze soubory, které se bezprostředně týkají Hibernate Search, kompletní zdrojáky aplikace jsou na konci příspěvku.

Závislosti

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

 <modelVersion>4.0.0</modelVersion>
 <groupId>org.hradil</groupId>
 <artifactId>HibernateSearchSimpleApplication</artifactId>
<packaging>war</packaging>
 <version>1.0</version>
 <name>Hibernate Search Simple Application</name>

 <dependencies>

 <!--  wicket -->
 <dependency>
 <groupId>org.apache.wicket</groupId>
 <artifactId>wicket</artifactId>
 <version>1.3.5</version>
 </dependency>

 <!-- wicket+spring -->
 <dependency>
 <groupId>org.apache.wicket</groupId>
 <artifactId>wicket-spring-annot</artifactId>
 <version>1.3.5</version>
 </dependency>

 <dependency>
 <groupId>org.hibernate</groupId>
 <artifactId>hibernate-entitymanager</artifactId>
 <version>3.4.0.GA</version>
 </dependency>

 <dependency>
 <artifactId>hibernate-annotations</artifactId>
 <groupId>org.hibernate</groupId>
 <version>3.4.0.GA</version>
 </dependency>

 <!-- Hibernate Search -->
 <dependency>
 <groupId>org.hibernate</groupId>
 <artifactId>hibernate-search</artifactId>
 <version>3.1.0.GA</version>
 </dependency>

 <dependency>
 <groupId>org.springframework</groupId>
 <artifactId>spring</artifactId>
 <version>2.5.5</version>
 <exclusions>
 <exclusion>
 <groupId>commons-logging</groupId>
 <artifactId>commons-logging</artifactId>
 </exclusion>
 </exclusions>
 </dependency>

 <!-- LOGGING DEPENDENCIES - LOG4J -->
 <dependency>
 <groupId>org.slf4j</groupId>
 <artifactId>slf4j-api</artifactId>
 <version>1.5.2</version>
 </dependency>

 <dependency>
 <groupId>org.slf4j</groupId>
 <artifactId>slf4j-log4j12</artifactId>
 <version>1.5.2</version>
 </dependency>

 <!-- work around for jetty commons logging issue -->
 <dependency>
 <groupId>org.slf4j</groupId>
 <artifactId>jcl-over-slf4j</artifactId>
 <version>1.5.2</version>
 </dependency>

 <dependency>
 <groupId>c3p0</groupId>
 <artifactId>c3p0</artifactId>
 <version>0.9.1.2</version>
 </dependency>

 <dependency>
 <groupId>postgresql</groupId>
 <artifactId>postgresql</artifactId>
 <version>8.2-507.jdbc3</version>
 <scope>compile</scope>
 </dependency>

 <!--  JUNIT DEPENDENCY FOR TESTING -->
 <dependency>
 <groupId>junit</groupId>
 <artifactId>junit</artifactId>
 <version>3.8.2</version>
 <scope>test</scope>
 </dependency>

 <!--  JETTY DEPENDENCIES FOR TESTING  -->

 <dependency>
 <groupId>org.mortbay.jetty</groupId>
 <artifactId>jetty</artifactId>
 <version>6.1.4</version>
 <scope>provided</scope>
 </dependency>

 </dependencies>

 <build>
 <resources>
 <resource>
 <directory>src/main/resources</directory>
 </resource>
 <resource>
 <directory>src/main/java</directory>
 <includes>
 <include>**</include>
 </includes>
 <excludes>
 <exclude>**/*.java</exclude>
 </excludes>
 </resource>
 </resources>
 <testResources>
 <testResource>
 <directory>src/test/java</directory>
 <includes>
 <include>**</include>
 </includes>
 <excludes>
 <exclude>**/*.java</exclude>
 </excludes>
 </testResource>
 </testResources>
<plugins>
<plugin>
 <groupId>org.mortbay.jetty</groupId>
 <artifactId>maven-jetty-plugin</artifactId>

 <configuration>
 <scanIntervalSeconds>5</scanIntervalSeconds>
 <contextPath>/</contextPath>
 </configuration>

 </plugin>
<plugin>
 <artifactId>maven-compiler-plugin</artifactId>
 <version>2.0.2</version>
 <configuration>
 <source>1.6</source>
 <target>1.6</target>
 </configuration>
 </plugin>

 </plugins>
 </build>

</project>

Konfigurace

applicationContext-jpa.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:tx="http://www.springframework.org/schema/tx"
 xsi:schemaLocation="
 http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
 http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd"
 >

 <description>
 Konfigurace kontextu pro JPA, vcetne datovych zdroju a transakcnich manazeru.
 </description>

 <bean id="dataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource" destroy-method="close">
 <description>
 Datovy zdroj pro persistentni vrstvu. Obsahuje udaje o pripojeni k databazi.
 </description>
<property name="driverClass" value="org.postgresql.Driver"/>
<property name="jdbcUrl" value="jdbc:postgresql://localhost/HibernateSearchSimple"/>
<property name="user" value="postgres"/>
<property name="password" value=""/>
 </bean>

 <bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
 <description>
 Tovarna pro manazer entit. Je pouzita trida LocalContainerEntityManagerFactoryBean,
 ktera je doporucena pro produkcni nasazeni JPA.
 Viz. http://static.springframework.org/spring/docs/2.5.x/reference/orm.html
 </description>
<property name="dataSource" ref="dataSource"/>
<property name="jpaVendorAdapter">
 <bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter">
<property name="databasePlatform" value="org.hibernate.dialect.PostgreSQLDialect" />
<property name="generateDdl" value="false"/>
 </bean>
 </property>

 <!-- nastaveni JPA a Hibernate Search -->
<property name="jpaProperties">

 <value>

 # konfigurace JPA
 hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
 hibernate.hbm2ddl.auto=validate

 # debugging / logging
 hibernate.show_sql=true
 hibernate.format_sql=true
 hibernate.use_sql_comments=true

 # konfigurace Hibernate Search
 # kde bude ulozen Lucene index
 hibernate.search.default.indexBase=/tmp/index

 </value>

 </property>
 </bean>

 <tx:annotation-driven transaction-manager="transactionManager"/>

 <!-- transakcni manazer -->
 <bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
<property name="entityManagerFactory" ref="entityManagerFactory"/>
 </bean>

</beans>

Entita

Company.java

package org.hradil.search.entity;

import java.io.Serializable;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.SequenceGenerator;
import javax.persistence.Table;
import org.hibernate.search.annotations.DocumentId;
import org.hibernate.search.annotations.Field;
import org.hibernate.search.annotations.Indexed;

/**
 * Entita reprezentuje firmu.
 * Firmu lze ve fulltextu vyhledat podle id, name a regNo.
 *
 * @author jirka@hradil.org
 */
@Entity
@Table(name = "company")
@Indexed //tridu budeme chtit indexovat ve fulltextu
public class Company implements Serializable {

 private static final long serialVersionUID = 1216348069826762176L;

 @Id
 @Column(name = "id")
 @SequenceGenerator(name = "company_id_seq", sequenceName = "company_id_seq")
 @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "company_id_seq")
 @DocumentId //primarni klic objektu ve fulltextu, zaroven podle nej muzeme vyhledavat
 private int id;

 @Column
 @Field //ve fulltextu chceme hledat firmu podle nazvu
 private String name;

 @Column
 @Field //ve fulltextu chceme hledat firmu podle IC
 private String regNo;

 /**
 * Vytvori novou firmu.
 */
 public Company() {
 }

 /**
 * Vytvori novou firmu a predvyplni atributy.
 * @param name nazev firmy
 * @param regNo IC
 */
 public Company(final String name, final String regNo) {
 this.name = name;
 this.regNo = regNo;
 }

 /**
 * Vrati id firmy
 * @return id
 */
 public int getId() {
 return id;
 }

 /**
 * Nastavi id firmy
 * @param id id
 */
 public void setId(int id) {
 this.id = id;
 }

 /**
 * Vrati nazev firmy.
 * @return nazev
 */
 public String getName() {
 return name;
 }

 /**
 * Nastavi nazev firmy.
 * @param name nazev
 */
 public void setName(String name) {
 this.name = name;
 }

 /**
 * Vrati IC firmy.
 * @return IC
 */
 public String getRegNo() {
 return regNo;
 }

 /**
 * Nastavi IC firmy.
 * @param regNo IC
 */
 public void setRegNo(String regNo) {
 this.regNo = regNo;
 }
}

Servisní vrstva - uložení, úprava, vyhledání

CompanyServiceImpl.java

package org.hradil.search.service;

import org.hradil.search.entity.Company;

import java.util.List;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import org.apache.lucene.analysis.standard.StandardAnalyzer;
import org.apache.lucene.queryParser.MultiFieldQueryParser;
import org.apache.lucene.queryParser.ParseException;
import org.apache.lucene.queryParser.QueryParser;
import org.apache.lucene.search.MatchAllDocsQuery;
import org.apache.lucene.search.Sort;
import org.apache.lucene.search.SortField;
import org.hibernate.search.jpa.FullTextQuery;
import org.hibernate.search.jpa.Search;
import org.hibernate.search.jpa.FullTextEntityManager;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.util.Assert;
import org.springframework.util.StringUtils;

/**
 * Implementace sluzby pro firmu.
 *
 * @author jirka@hradil.org
 */
@Transactional(propagation = Propagation.REQUIRED)
@Service
public class CompanyServiceImpl implements CompanyService {

 @PersistenceContext
 private EntityManager em;

 /**
 * {@inheritDoc}
 */
 @Override
 public void addCompany(Company newCompany) {
 em.persist(newCompany);
 }

 /**
 * {@inheritDoc}
 */
 @Override
 @SuppressWarnings("unchecked")
 @Transactional(readOnly = true)
 public List<Company> findCompanyBy(final String fulltextQuery) {

 Assert.notNull(fulltextQuery, "retezec pro vyhledavani nesmi byt null!");

 //vezmeme instanci manazeru fulltextu
 FullTextEntityManager ftEm = Search.getFullTextEntityManager(em);

 //vytvorime parser pro prohledavane atributy firmy, pouzijeme standardni analyzer
 QueryParser parser = new MultiFieldQueryParser(new String[]{"id", "name", "regNo"}, new StandardAnalyzer());

 //vytvorime dotaz do Lucene
 org.apache.lucene.search.Query luceneQuery;

 //pokud po zruseni vsech bilych znaku a hvezdicek zustane jen prazdny retezec, pak vracime vsechny zaznamy
 //napr. dotaz "**** * **  *" bude vyhodnocen tak, ze chceme prohledavat vsechny firmy
 if (StringUtils.trimAllWhitespace(StringUtils.deleteAny(fulltextQuery, "*")).isEmpty()) {
 luceneQuery = new MatchAllDocsQuery();
 } else { //byl zadan retezec, vyhledavame
 try {
 luceneQuery = parser.parse(fulltextQuery); //zparsujeme predany dotaz pomoci parseru Lucene
 } catch (ParseException e) { //neplatny dotaz, prekonverujeme na runtime vyjimku, nemusime zachytavat
 throw new RuntimeException("Neplatny dotaz do fulltextu: " + fulltextQuery, e);
 }
 }

 //vytvorime normalni JPA dotaz, ale pres rozhrani fulltextu
 FullTextQuery query = ftEm.createFullTextQuery(
 luceneQuery,
 Company.class);

 //tridime dle relevance DESC, pote dle id DESC
 SortField[] sortFields = new SortField[2];
 sortFields[0] = SortField.FIELD_SCORE; //relevance, default DESC
 sortFields[1] = new SortField("id", SortField.INT, true); //id, je to intener, DESC=true
 Sort sort = new Sort(sortFields);

 //pridame trideni do dotazu
 query.setSort(sort);

 //a vratime rovnou vyhovujici seznam firem z ORM
 return query.getResultList();

 }

 /**
 * {@inheritDoc}
 */
 @Override
 @SuppressWarnings("unchecked")
 @Transactional(readOnly = true)
 public Company findCompanyBy(int id) {
 return em.find(Company.class, id);
 }

 @Override
 @Transactional(readOnly = false)
 public void updateCompany(Company company) {
 em.merge(company);
 }
}

Zdrojové kódy aplikace

hibernatesearchsimple

Konfiguraci a rozjetí v clusteru si ukážeme v některém dalším příspěvku.