From hibernate-commits at lists.jboss.org Mon Aug 23 13:57:51 2010
Content-Type: multipart/mixed; boundary="===============5813101446446156559=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r20236 -
search/trunk/hibernate-search/src/main/docbook/en-US/modules.
Date: Mon, 23 Aug 2010 13:57:51 -0400
Message-ID: <201008231757.o7NHvpOS028515@svn01.web.mwc.hst.phx2.redhat.com>
--===============5813101446446156559==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Author: epbernard
Date: 2010-08-23 13:57:50 -0400 (Mon, 23 Aug 2010)
New Revision: 20236
Modified:
search/trunk/hibernate-search/src/main/docbook/en-US/modules/query.xml
Log:
HSEARCH-563 Fix many style issues on html rendering
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/quer=
y.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/query.xml =
2010-08-23 17:57:17 UTC (rev 20235)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/query.xml =
2010-08-23 17:57:50 UTC (rev 20236)
@@ -77,7 +77,9 @@
If you use the Hibernate Search query DSL, it will look like
this:
=
- =
final QueryBuilder b =3D fullTextSession.getSearchFactory().buildQueryBuild=
er().forEntity( Myth.class ).get();
+ =
final QueryBuilder b =3D fullTextSession.getSearchFactory()
+ .buildQueryBuilder().forEntity( Myth.class ).get();
+
org.apache.lucene.search.Query luceneQuery =3D
b.keyword()
.onField("history").boostedTo(3)
@@ -95,8 +97,9 @@
Creating a Lucene query from scratch via the query parser</titl=
e>
=
- <programlisting language=3D"JAVA" role=3D"JAVA"><emphasis role=3D"bold=
">org.apache.lucene.queryParser.QueryParser parser =3D =
- new QueryParser("title", fullTextSession.getSearchFactory().getAnalyze=
r(Myth.class) );
+ <programlisting language=3D"JAVA" role=3D"JAVA"><emphasis role=3D"bold=
">SearchFactory searchFactory =3D fullTextSession.getSearchFactory();
+org.apache.lucene.queryParser.QueryParser parser =3D =
+ new QueryParser("title", searchFactory.getAnalyzer(Myth.class) );
try {
org.apache.lucene.search.Query luceneQuery =3D parser.parse( "history:=
storm^3" );
}
@@ -104,7 +107,7 @@
//handle parsing failure
}</emphasis>
=
-org.hibernate.Query fullTextQuery =3D fullTextSession.createFullTextQuery(=
luceneQuery );
+org.hibernate.Query fullTextQuery =3D fullTextSession.createFullTextQuery(=
luceneQuery);
List result =3D fullTextQuery.list(); //return a list of managed objects =
</programlisting>
</example>
=
@@ -121,20 +124,23 @@
<example>
<title>Creating a Search query using the JPA API
=
- EntityManager em =3D entit=
yManagerFactory.createEntityManager();
+ EntityManager em =3D e=
ntityManagerFactory.createEntityManager();
=
FullTextEntityManager fullTextEntityManager =3D =
org.hibernate.search.jpa.Search.getFullTextEntityManager(em);
=
...
-final QueryBuilder b =3D fullTextEntityManager.getSearchFactory().buildQue=
ryBuilder().forEntity( Myth.class ).get();
+final QueryBuilder b =3D fullTextEntityManager.getSearchFactory()
+ .buildQueryBuilder().forEntity( Myth.class ).get();
+
org.apache.lucene.search.Query luceneQuery =3D
b.keyword()
.onField("history").boostedTo(3)
.matching("storm")
.createQuery();
+javax.persistence.Query fullTextQuery =3D =
+ fullTextEntityManager.createFullTextQuery( luceneQuery );
=
-javax.persistence.Query fullTextQuery =3D fullText=
EntityManager.createFullTextQuery( luceneQuery );
List result =3D fullTextQuery.getResultList(); //return a list of managed =
objects
=
@@ -214,15 +220,16 @@
QueryBuilder from the
SearchFactory.
=
- QueryBuilder mythQB =3D =
searchFactory.buildQueryBuilder().forEntity( Myth.class ).get();
+ QueryBuilder mythQB =
=3D searchFactory
+ .buildQueryBuilder().forEntity( Myth.class ).get();
=
You can also override the analyzer used for a given field or
fields. This is rarely needed and should be avoided unless you know =
what
you are doing (like many things :)).
=
- QueryBuilder mythQB =3D =
searchFactory.buildQueryBuilder()
+ QueryBuilder mythQB =
=3D searchFactory.buildQueryBuilder()
.forEntity( Myth.class )
- .overridesForField("history","stem_analyzer_definition");
+ .overridesForField("history","stem_analyzer_definition")
.get();
=
From the query builder, you are then ready to... build queries.
@@ -234,7 +241,8 @@
=
Here is how you search for a specific word:
=
- Query luceneQuery =
=3D mythQB.keyword().onField("history").matching("storm").createQuery();
+ Query luceneQuery =
=3D =
+ mythQB.keyword().onField("history").matching("storm").createQuery();
=
keyword() means that you are trying to
find a specific word. onField() tells in wh=
ich
@@ -265,7 +273,8 @@
Let's see how you can search a property that is not of type
string.
=
- @Entity @Indexed cla=
ss Myth {
+ @Entity @Indexed =
+public class Myth {
@Field(index =3D Index.UN_TOKENIZED) @DateBridge(resolution =3D Resoluti=
on.YEAR)
public Date getCreationDate() { return creationDate; }
public Date setCreationDate(Date creationDate) { this.creationDate =3D c=
reationDate; }
@@ -275,7 +284,9 @@
}
=
Date birthdate =3D ...;
-Query luceneQuery =3D mythQb.keywork().onField("creationDate").matching(bi=
rthdate).createQuery();
+Query luceneQuery =3D =
+ mythQb.keywork().onField("creationDate").matching(birthdate).createQue=
ry();
+
=
In plain Lucene, you would have had to convert the
@@ -305,8 +316,10 @@
@Parameter(name =3D "maxGramSize", value =3D "3") } )
}
)
-(a)Entity @Indexed class Myth {
- @Field(analyzer=3D@Analyzer(definition=3D"ngram") @DateBridge(resolution=
=3D Resolution.YEAR)
+(a)Entity @Indexed =
+public class Myth {
+ @Field(analyzer=3D@Analyzer(definition=3D"ngram") =
+ @DateBridge(resolution =3D Resolution.YEAR)
public String getName() { return name; }
public String setName(Date name) { this.name =3D name; }
private String name;
@@ -315,7 +328,8 @@
}
=
Date birthdate =3D ...;
-Query luceneQuery =3D mythQb.keywork().onField("name").matching("Sisiphus"=
).createQuery();
+Query luceneQuery =3D mythQb.keyword().onField("name").matching("Sisiphus"=
).createQuery();
+
=
The matching word "Sisiphus" will be lower-cased and then split
into 3-grams: sis, isi, sip, phu, hus. Each of these n-gram will be =
part
@@ -333,12 +347,17 @@
add them all in the matching clause.
=
//search document wi=
th storm or lightning in their history
-Query luceneQuery =3D mythQB.keyword().onField("history").matching("storm =
lightning").createQuery();
+Query luceneQuery =3D =
+ mythQB.keyword().onField("history").matching("storm lightning").create=
Query();
=
To search the same word on multiple fields, use the
onFields method.
=
- Query luceneQuery =
=3D mythQB.keyword().onFields("history","description","name").matching("sto=
rm").createQuery();
+ Query luceneQuery =
=3D mythQB
+ .keyword()
+ .onFields("history","description","name")
+ .matching("storm")
+ .createQuery();
=
Sometimes, one field should be treated differently from another
field even if searching the same term, you can use the
@@ -439,24 +458,23 @@
=
- SHOULD: the query query should contain the matching elemen=
ts
- of the subquery
+ SHOULD: the query query should contain =
the
+ matching elements of the subquery
=
- MUST: the query must contain the matching elements of the
- subquery
+ MUST: the query must contain the matchi=
ng
+ elements of the subquery
=
- MUST NOT: the query must not contain the matching elements=
of
- the subquery
+ MUST NOT: the query must not contain the
+ matching elements of the subquery
=
The subqueries can be any Lucene query including a boolean que=
ry
- itself. Let's look at a few examples://look for popular modern myths that are not urban
+ itself. Let's look at a few examples://look for popular modern myths that=
are not urban
Date twentiethCentury =3D ...;
Query luceneQuery =3D mythQB
.bool()
@@ -475,7 +493,9 @@
//look for all myths except religious ones
Query luceneQuery =3D mythQB
.all()
- .except( monthQb.keyword().onField( "description_stem" ).matching( "=
religion" ).createQuery() )
+ .except( =
+ monthQb.keyword().onField( "description_stem" ).matching( "religio=
n" ).createQuery() =
+ )
.createQuery();
=
You can apply some options to query types and fields:
@@ -512,7 +532,7 @@
=
Let's check out an example using some of these options
=
- Query luceneQuery =3D mythQB
+ Query luceneQuery =
=3D mythQB
.bool()
.should( mythQB.keyword().onField("description").matching("urban").c=
reateQuery() )
.should( mythQB
@@ -525,7 +545,8 @@
.range()
.boostedTo(5).withConstantScore()
.onField("starred").above(4).createQuery() )
- .createQuery();
+ .createQuery();
+
=
As you can see, Hibernate Search query DSL is a fairly high and
easy to read query API. By accepting and producing Lucene queries, y=
ou
@@ -548,8 +569,9 @@
Wrapping a Lucene query into a Hibernate Query
=
- FullTextSession fullTextSession =3D Search.getFu=
llTextSession( session );
-org.hibernate.Query fullTextQuery =3D fullTextSession.createFullTextQuery(=
luceneQuery );
+ FullTextSession =
fullTextSession =3D Search.getFullTextSession( session );
+org.hibernate.Query fullTextQuery =3D =
+ fullTextSession.createFullTextQuery( luceneQuery );
=
If not specified otherwise, the query will be executed again=
st
@@ -560,9 +582,13 @@
Filtering the search result by entity type
=
- org.hibernate.Query fullTextQuery =3D fullTextSe=
ssion.createFullTextQuery( luceneQuery, Customer.class );
+ org.hibernate.Qu=
ery fullTextQuery =3D =
+ fullTextSession.createFullTextQuery( luceneQuery, Customer.class );
+
// or
-fullTextQuery =3D fullTextSession.createFullTextQuery( luceneQuery, Item.c=
lass, Actor.class );
+
+fullTextQuery =3D =
+ fullTextSession.createFullTextQuery( luceneQuery, Item.class, Actor.cl=
ass );
=
The first example returns only matching
@@ -588,7 +614,8 @@
Defining pagination for a search query
=
- org.hibernate.Query fullTextQuery =3D fullTextSe=
ssion.createFullTextQuery( luceneQuery, Customer.class );
+ org.hibernate.Qu=
ery fullTextQuery =3D =
+ fullTextSession.createFullTextQuery( luceneQuery, Customer.class );
fullTextQuery.setFirstResult(15); //start from the 15th element
fullTextQuery.setMaxResults(10); //return 10 elements
@@ -613,10 +640,12 @@
Specifying a Lucene <classname>Sort</classname> in order =
to
sort the results
=
- org.hibernate.search.FullTextQuery query =3D s.c=
reateFullTextQuery( query, Book.class );
+
+org.hibernate.search.FullTextQuery query =3D s.createFullTextQuery( query,=
Book.class );
org.apache.lucene.search.Sort sort =3D new Sort(new SortField("title"));
query.setSort(sort);
-List results =3D query.list();
+List results =3D query.list();
+
=
One can notice the FullTextQuery
@@ -639,7 +668,8 @@
Specifying <classname>FetchMode</classname> on a
query
=
- Criteria criteria =3D s.createCriteria( Book.cla=
ss ).setFetchMode( "authors", FetchMode.JOIN );
+ Criteria criteri=
a =3D =
+ s.createCriteria( Book.class ).setFetchMode( "authors", FetchMode.JOIN=
);
s.createFullTextQuery( luceneQuery ).setCriteriaQuery( criteria );
=
@@ -668,7 +698,8 @@
Using projection instead of returning the full domain
object
=
- org.hibernate.search.FullTextQuery query =3D s.c=
reateFullTextQuery( luceneQuery, Book.class );
+ org.hibernate.search.FullTextQuery query =3D =
+ s.createFullTextQuery( luceneQuery, Book.class );
query.setProjection( "id", "summary", "body", "mai=
nAuthor.name" );
List results =3D query.list();
Object[] firstResult =3D (Object[]) results.get(0);
@@ -721,8 +752,12 @@
Using projection in order to retrieve meta data
=
- org.hibernate.search.FullTextQuery query =3D s.c=
reateFullTextQuery( luceneQuery, Book.class );
-query.setProjection( FullTextQuery.SCORE, FullText=
Query.THIS, "mainAuthor.name" );
+ org.hibernate.search.FullTextQuery query =3D =
+ s.createFullTextQuery( luceneQuery, Book.class );
+query.setProjection( =
+ FullTextQuery.SCORE, =
+ FullTextQuery.THIS, =
+ "mainAuthor.name" );
List results =3D query.list();
Object[] firstResult =3D (Object[]) results.get(0);
float score =3D firstResult[0];
@@ -845,13 +880,17 @@
Determining the result size of a query
=
- org.hibernate.search.FullTextQuery query =3D s.cre=
ateFullTextQuery( luceneQuery, Book.class );
-assert 3245 =3D=3D query.getResultSize(); //return the number of matching books without loading a single one
+ org.hibernate.search.FullTextQuery query =3D =
+ s.createFullTextQuery( luceneQuery, Book.class );
+//return the number of matching books without loading a single one
+assert 3245 =3D=3D query.getResultSize(); =
=
-org.hibernate.search.FullTextQuery query =3D s.createFullTextQuery( lucene=
Query, Book.class );
+org.hibernate.search.FullTextQuery query =3D =
+ s.createFullTextQuery( luceneQuery, Book.class );
query.setMaxResult(10);
List results =3D query.list();
-assert 3245 =3D=3D query.getResultSize(); //return the total number of matching books regardless of pagination
+//return the total number of matching books regardless of pagination
+assert 3245 =3D=3D query.getResultSize();
=
@@ -873,11 +912,15 @@
Using ResultTransformer in conjunction with projections</ti=
tle>
=
- <programlisting>org.hibernate.search.FullTextQuery query =3D s.cre=
ateFullTextQuery( luceneQuery, Book.class );
+ <programlisting>org.hibernate.search.FullTextQuery query =3D =
+ s.createFullTextQuery( luceneQuery, Book.class );
query.setProjection( "title", "mainAuthor.name" );
=
<emphasis role=3D"bold">query.setResultTransformer( =
- new StaticAliasToBeanResultTransformer( BookView.class, "title", "auth=
or" ) =
+ new StaticAliasToBeanResultTransformer( =
+ BookView.class, =
+ "title", =
+ "author" ) =
);</emphasis>
List<BookView> results =3D (List<BookView>) query.list();
for(BookView view : results) {
@@ -931,7 +974,10 @@
projection
=
FullTextQuery ftQuery =3D s.createFullTextQuery( l=
uceneQuery, Dvd.class )
- .setProjection( FullTextQuery.DOCUMENT_ID, FullTextQuery.EXPLANATION, FullTextQuery.THIS );
+ .setProjection( =
+ FullTextQuery.DOCUMENT_ID, =
+ FullTextQuery.EXPLANATION, =
+ FullTextQuery.THIS );
@SuppressWarnings("unchecked") List<Object[]> results =3D ftQuery.li=
st();
for (Object[] result : results) {
Explanation e =3D (Explanation) result[1];
--===============5813101446446156559==--