senselogic.sitevision.api.search.searcher.builder

Interface HighlightBuilder

All Superinterfaces:

Builder<Highlight>

@Requireable(value="HighlightBuilder")
public interface HighlightBuilder
extends Builder<Highlight>

Builder for creating a Highlight component with specific behaviour.

HighlightBuilder has one mandatory attribute:

• highlighted field - The name of the field(s) that should be highlighted. Must be non-null.

HighlightBuilder also has some optional attributes:

• fragment char count - The size of a highlighted fragment. Default is 200.
• fragment pre string - The start value of a highlighted section of a fragment. Default is "<mark>".
• fragment post string - The end value of a highlighted section of a fragment. Default is "</mark>".

Using the HighlightBuilder is pretty straightforward, if you remember that it is stateful. Conceptually you would typically use it like this:

1. Get the HighlightBuilder
2. Add a highlighted field
3. Possibly set a char count
4. Possibly set pre + post
5. Do build

When you have built a Highlight instance, you can re-use the HighlightBuilder to build more instances. Typically like:

1. Clear the highlighted fields
2. Possibly change char count
3. Possibly change pre + post
4. Do build

Example of how this strategy could be implemented in Velocity:

   ## Get the builder
   #set ($searchFactory = $sitevisionUtils.searchFactory)
   #set ($highlightBuilder = $searchFactory.highlightBuilder)

   ## Create a Highlight
   #set ($summaryHighlight = $highlightBuilder.addHighlightedField('summary').build())

   ## Re-use the builder to create another Highlight
   #set ($nameHighlight = $highlightBuilder.clearHighlightedFields().addHighlightedField('name').build())
 

Tip! The Builder interface documentation contains more information about Builders and how to work with them!

An instance of the Sitevision class implementing this interface can be obtained via SearchFactory.getHighlightBuilder(). See SearchFactory for how to obtain an instance of the SearchFactory interface.

Since:

Sitevision 3.6

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
HighlightBuilder	addHighlightedField(String aHighlightedField) Adds a field that should be highlighted.
Highlight	build() Creates a Highlight component instance using currently specified state/behaviour.
HighlightBuilder	clearHighlightedFields() Removes all previously added highlighted fields.
HighlightBuilder	setFragmentCharCount(int aCharCount) Sets the number of chars that highlighted fragment should contain.
HighlightBuilder	setFragmentPostString(String aPostString) Sets the end value for the highlighted section(s) of a fragment.
HighlightBuilder	setFragmentPreString(String aPreString) Sets the start value for the highlighted section(s) of a fragment.

Method Detail

addHighlightedField

HighlightBuilder addHighlightedField(String aHighlightedField)

Adds a field that should be highlighted.

Solr note: this is the 'hl.fl' param

Parameters:

aHighlightedField - name of the field, a null or whitespace-only value will be ignored

Returns:

this builder

clearHighlightedFields

HighlightBuilder clearHighlightedFields()

Removes all previously added highlighted fields.

Returns:

this builder

setFragmentCharCount

HighlightBuilder setFragmentCharCount(int aCharCount)
                               throws IllegalArgumentException

Sets the number of chars that highlighted fragment should contain.

If no char count is specified, the default value of the index config will be used (200).

Solr note: this is the 'hl.fragsize' param

Parameters:

aCharCount - the char count

Returns:

this builder

Throws:

IllegalArgumentException - if aCharCount is zero or negative

setFragmentPreString

HighlightBuilder setFragmentPreString(String aPreString)

Sets the start value for the highlighted section(s) of a fragment.

If the pre string and post string are not specified, the default value of the index config will be used ('<mark>' and '</mark>').

Solr note: this is the 'hl.simple.pre' param

Parameters:

aPreString - a fragment start

Returns:

this builder

setFragmentPostString

HighlightBuilder setFragmentPostString(String aPostString)

Sets the end value for the highlighted section(s) of a fragment.

Note! The fragment pre value must match the fragment post string! E.g: if the pre string is "<em>", the post string would typically be "</em>".

Solr note: this is the 'hl.simple.post' param

Parameters:

aPostString - a fragment end

Returns:

this builder

build

Highlight build()
         throws IllegalStateException

Creates a Highlight component instance using currently specified state/behaviour.

Specified by:

build in interface Builder<Highlight>

Returns:

a Highlight component

Throws:

IllegalStateException - if no highlighted field is specified, or if pre and post strings doesn't match (e.g. one of them is null)