Hibernate Search – fulltext nad Hibernate ORM
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
Konfiguraci a rozjetí v clusteru si ukážeme v některém dalším příspěvku.
).
:-D ale mám-li to celé...