## Using the Lucene Control

The Lucene Control provides two methods: one to put data into the Lucene search index, and another to execute queries on the index.

### Indexing Data

The operation to index data is as follows:

    public void index(LuceneField []fields)

where LuceneField is a name/value pair, as follows:

    public class LuceneField {

    	public LuceneField(String name, String value){...}

    	public String getName(){...}

    	public String getValue(){...}

    }

The array of LuceneFields passed to the index operation are considered to belong to the same "document". What this means is that a query on any field will make available the entire array of fields that were indexed with that field. An example should help to make it clear. Imagine you are indexing an email message.

    EmailMessage email = ...

    LuceneField fromField = new LuceneField("from", email.getFrom());

    LuceneField toField = new LuceneField("to", email.getTo());

    LuceneField subjectField = new LuceneField("subject", email.getSubject());

    luceneControl.index(new LuceneField[]{fromField, toField, subjectField});

Now fromField, toField and subjectField are considered to belong to the same "document". If you (later) execute a query on the fromField, for example, the toField and the subjectField will also be available to you in the query result, thereby enabling you to reconstitute the entire document.

### Searching Data

The operation to search data is as follows:

    public LuceneHit[] search(String query, String searchFieldName, String[] returnFieldNames)

The query is a plain query as you would enter into any search engine. The searchFieldName is the name of the field you want to query on. For example, "subject" is a possibility using the email example above. returnFieldNames is an array of names of LuceneFields that you want returned. You may, for example, use "from" and "to" using the email example above. LuceneHit is as follows:

    public class LuceneHit {

        public Map getFields(){...}

        public float getScore(){...}

    }

The score is a measure of how good a metch the Hit is. Its a value ranging from 0 to 1, with 1 being a perfect match. getFields() returns a Map containing LuceneField instanced keyed by name. This map will contain the LuceneFields you asked to have returned by specifying their names in the returnFieldNames string array in the search operation. It is best explained by way of example:

    LuceneHit []hits = luceneControl.search("tom@acme.com", "from", new String[]{"from","to","subject"});

    System.out.println("The number of emails from tom@acme.com is " + hits.length);

    LuceneHit firstHit = hits[0];

    System.out.println("Here is the content of the first email in the result list:");

    System.out.println("from: " + ((LuceneField)firstHit.getFields().get("from")).getValue());

    System.out.println("to: " + ((LuceneField)firstHit.getFields().get("to")).getValue());

    System.out.println("subject: " + ((LuceneField)firstHit.getFields().get("subject")).getValue());