Query Bean Samples

NB. You need to make an index first.
If you have not already made an index of the Cocoon Documentation, you may do so here.

This sample currently does not work. This sample used to use the docs built-in to Cocoon as a search target. While the new documentation effort is in flux, there is nothing to index. Try this sample in the current 2.1 version.

Search

You can perform any of the following search types:

Queries

You can view, reuse, and re-edit your previous queries:

What it does.

Allows you to assemble complex Lucene Queries without having to use the Lucene Query Language. Keeps a list of the queries you have performed in it's history (for as long as your Session lasts). Allows you to re-use and edit them.

How does it work?

Through a combination of FlowScript (controller), CForms and JXTemplate (view), Beans and OJB (model), i18n and the CocoonLuceneSearcher component.

FlowScript

The FlowScript controls the flow of the application, it instansiates Beans, manages the History, chooses which Forms and Screens to display, controls the CocoonLuceneSearcher.

CForms

Cocoon Forms provideds the infrastructure to manipulate the Beans via HTML Forms. That is to change the Properties of the Beans and add and remove Criteria.

JXTemplate

JXTemplate is used to show the results and the history (List of Query Beans).

The results are in the form of a List of Maps. Each Map represents a search hit. It contains the url, score and rank of the document, plus any Index Fields you arranged to have stored in your Index by Lucene (in this sample, the only stored field is the title).

The history is in the form of a List of Query Beans.

Beans

The Beans represent an abstract (and persistable) representation of your Query.

i18n

i18n is used to hold all of the display strings used by the Application. Form labels and hints, Query descriptions, Screen labels and hints, Error messages etc.

CocoonLuceneSearcher

This is the Component that does the actual searching. It is provided with the Lucene Directory and a Query by the Query Bean. If you give it a directory parameter that is a single folder name, it uses that folder in the Servlet Engine's Work Directory, if the parameter is an absolute file path, it uses that instead. It uses the default Analyser.

How to reuse this sample in your own projects?

Reuse the existing forms

If you are happy with the existing forms, then all that really needs to happen to be able to re-use this sample in your own projects it to set up the menu of Search Fields, so they match your Search Index.

When the Lucene Index of Cocoon Documentation that this sample uses is created, tags within the documents are turned into Lucene Index Fields, which can be searched individually. The names of these fields are for example: title, question, source, person@name etc.

Cocoon Forms is setup to load these menus (selection-lists) from their own files. The simple search form uses the file forms/simple-fields.xml, while the advanced search form uses the file forms/advanced-fields.xml.

Edit these files to match your own Search Index, for example, the item:

<fd:item value="title">
	<fd:label><i18n:text i18n:catalogue="local">field.title.label</i18n:text></fd:label>
</fd:item>
makes a menu item using the i18n key field.title.label as the menu text and title as the value, where the value matches one of your Index Fields.

Once your CForms selection-lists are setup, you will want to edit the existing i18n message keys in i18n/messages_en.xml and/or provide new message files in your own language.

The last thing you may choose to do, is to supply some CSS for the screens. The history, favourites and results screens supply what is hopefully a rich enough collection of CSS Classes, have a look at the HTML output to see what there is.

New Forms

If you know CForms, it would be relatively easy to develop your own Forms (Model, Binding and Template). If you follow the existing naming scheme and you choose a new name for your form, it may not even be necessary to edit the Sitemap.

Depending on how different your Forms are to the supplied ones, it may or may not be necessary to edit the FlowScript. It is quite possible that this will not be required.

New Beans

It is possible to build Lucene Queries that are more complex, or specialised than those produced by these sample Beans. To do so you would have to at least implement your own CriterionBean. You would probably need to rewrite the FlowScript to handle your new Bean.

It would also be possible to implement different kinds of Queries, like those that used the Hibernate Criterion API.

There are two Interfaces and two Bean Implementations of those Interfaces in the sample. o.a.c.bean.query.SimpleLuceneQuery and o.a.c.bean.query.SimpleLuceneQueryBean represent a Query, which has a Collection of o.a.c.bean.query.SimpleLuceneCriterion (o.a.c.bean.query.SimpleLuceneCriterionBean) Beans.

The bool property of the QueryBean specifies how the multiple criteria are combined. The field property of the CriterionBean specifies which Index Field to search, the match property specifies how to match that field and the value property, is the string from which Terms are extracted. All the rest is candy.

Persistance

Both the Query and Criterion Beans were designed to be Persistable using one of the Object-Relational mapping tools like Hibernate, OJB etc. This sample currently uses the HSQLDB instance built in to Cocoon.