Return-Path: 
 <commits-return-4019-apmail-jackrabbit-commits-archive=jackrabbit.apache.org@jackrabbit.apache.org>
Delivered-To: apmail-jackrabbit-commits-archive@www.apache.org
Received: (qmail 16471 invoked from network); 15 May 2007 13:31:26 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 15 May 2007 13:31:26 -0000
Received: (qmail 68811 invoked by uid 500); 15 May 2007 13:31:32 -0000
Delivered-To: apmail-jackrabbit-commits-archive@jackrabbit.apache.org
Received: (qmail 68775 invoked by uid 500); 15 May 2007 13:31:32 -0000
Mailing-List: contact commits-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@jackrabbit.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@jackrabbit.apache.org>
List-Post: <mailto:commits@jackrabbit.apache.org>
List-Id: <commits.jackrabbit.apache.org>
Reply-To: dev@jackrabbit.apache.org
Delivered-To: mailing list commits@jackrabbit.apache.org
Received: (qmail 68763 invoked by uid 99); 15 May 2007 13:31:32 -0000
Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 15 May 2007 06:31:32 -0700
X-ASF-Spam-Status: No, hits=-100.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.130] (HELO eos.apache.org) (140.211.11.130)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 15 May 2007 06:31:25 -0700
Received: from eos.apache.org (localhost [127.0.0.1])
	by eos.apache.org (Postfix) with ESMTP id E9F3E59A07
	for <commits@jackrabbit.apache.org>; Tue, 15 May 2007 13:31:04 +0000 (GMT)
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: Apache Wiki <wikidiffs@apache.org>
To: commits@jackrabbit.apache.org
Date: Tue, 15 May 2007 13:31:04 -0000
Message-ID: <20070515133104.28764.12398@eos.apache.org>
Subject: [Jackrabbit Wiki] Update of "ExcerptProvider" by MarcelReutegger
X-Virus-Checked: Checked by ClamAV on apache.org

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jackrabbit Wiki" for change notification.

The following page has been changed by MarcelReutegger:
http://wiki.apache.org/jackrabbit/ExcerptProvider

New page:
An ExcerptProvider retrieves text excerpts for a node in the query result and marks up the words in the text that match the query terms.

This feature is Jackrabbit specific (introduced in version 1.3) and will not work with other JCR implementations.

Per default highlighting words that matched the query is disabled because this feature requires that additional information is written to the search index. To enable this feature you need to add the following parameter inside the SearchIndex element of your workspace.xml or repository.xml file:

{{{
   <param name="supportHighlighting" value="true"/>
}}}

Additionally there is a parameter that controls the format of the excerpt created. In Jackrabbit 1.3 the default is set to {{{org.apache.jackrabbit.core.query.lucene.DefaultXMLExcerpt}}} and will be changed to {{{org.apache.jackrabbit.core.query.lucene.DefaultHTMLExcerpt}}} in Jackrabbit 1.4. The configuration parameter for this setting is:

{{{
   <param name="excerptProviderClass" value="org.apache.jackrabbit.core.query.lucene.DefaultXMLExcerpt"/>
}}}

=== DefaultXMLExcerpt ===

This excerpt provider creates an XML fragment of the following form:

{{{
<excerpt>
    <fragment>
        <highlight>Jackrabbit</highlight> implements both the mandatory
        XPath and optional SQL <highlight>query</highlight> syntax.
    </fragment>
    <fragment>
        Before parsing the XPath <highlight>query</highlight> in
        <highlight>Jackrabbit</highlight>, the statement is surrounded
    </fragment>
</excerpt>
}}}

=== DefaultHTMLExcerpt ===

This excerpt provider creates an HTML fragment of the following form:

{{{
<div>
    <span>
        <strong>Jackrabbit</strong> implements both the mandatory XPath
        and optional SQL <strong>query</strong> syntax.
    </span>
    <span>
        Before parsing the XPath <strong>query</strong> in
        <strong>Jackrabbit</strong>, the statement is surrounded
    </span>
</div>
}}}

=== How to use it ===

If you are using XPath you must use the {{{rep:excerpt()}}} function in the last location step, just like you would select properties:

{{{
QueryManager qm = session.getWorkspace().getQueryManager();
Query q = qm.createQuery("//*[jcr:contains(., 'jackrabbit')]/(@Title|rep:excerpt(.))", Query.XPATH);
QueryResult result = q.execute();
for (RowIterator it = result.getRows(); it.hasNext(); ) {
    Row r = it.nextRow();
    Value title = r.getValue("Title");
    Value excerpt = r.getValue("rep:excerpt(.)");
}
}}}

The above code searches for nodes that contain the word jackrabbit and then gets the value of the Title property and an excerpt for each result node.

Starting with Jackrabbit 1.4 it is also possible to use a relative path in the call {{{Row.getValue()}}} while the query statement still remains the same. See [http://issues.apache.org/jira/browse/JCR-860 JCR-860] for more information. Also starting with Jackrabbit 1.4 you may use a relative path to a string property. The returns value will then be an excerpt based on string value of the property.

Both available excerpt provider will create fragments of about 150 characters and up to 3 fragments.

In SQL the function is called {{{excerpt()}}} without the rep prefix, but the column in the RowIterator will nonetheless be labled rep:excerpt(.)!

{{{
QueryManager qm = session.getWorkspace().getQueryManager();
Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'jackrabbit')", Query.SQL);
QueryResult result = q.execute();
for (RowIterator it = result.getRows(); it.hasNext(); ) {
    Row r = it.nextRow();
    Value excerpt = r.getValue("rep:excerpt(.)");
}
}}}