Personalization Hub Manual / Version 2301
Table Of Contents
The SearchFunctionPreprocessor
maintains a map of search function names and implementations. The
registered name of a function is used to call it from within the query string and, if a call is encountered in
the query, it's replaced by the result of the executed implementation.
A search function implementation is an instance of a Java class that implements the SearchFunction
interface. This interface contains a single method only; evaluate
. The preprocessor supplies the
ContextCollection
associated with the current request and all function arguments supplied in the
function call to this method.
What's happening inside of the evaluate method is entirely up to you. The only constraint is that the resulting string should by a syntactically valid (sub)query to your Search Engine.
Search function arguments are in the form <parameter name>:<value>
and are supplied to
a function in an instance of class SearchFunctionArguments
. The latter provides a number of
convenience methods to access arguments and convert their values to appropriate types.
If you implement your own search functions, make sure they are thread safe because the
SearchFunctionPreprocessor
is usually declared as a singleton Spring bean. This means that several
request threads may access the preprocessor and the registered search functions in parallel.
Example
The search function SolrGeneralProperty
, which is provided as part of
CoreMedia Adaptive Personalization, provides access to a general context
property from within a query in Solr syntax. If it is registered with the
SearchFunctionPreprocessor
under the name "contextProperty", preprocessing the query
recommendations contextProperty(property:personal.name, field:user)
calls the evaluate
method of the registered instance of SolrGeneralProperty
supplying the current
ContextCollection
and function arguments property:personal.name
and
field:user
.
SolrGeneralProperty
looks up the context object named "personal" in the
ContextCollection
and retrieves the value of its property name, which is assumed to be "bob". Then,
it concatenates the field argument with the retrieved name to the valid Solr search query "user:bob" and returns
this string.
The preprocessor replaces the function call by the returned string, resulting in the query "recommendations user:bob".
Exception Handling
The SearchFunctionPreprocessor
wraps any exception that is thrown while evaluating a search function's
evaluate method in a runtime exception of type SearchFunctionEvaluationException
. In addition to
the exception cause, the SearchFunctionEvaluationException
is supplied with the name under which
the executing search function is registered.
Implementations of SearchFunction
are encouraged to use one of the Argument*Exception
classes if there is any problem with the arguments supplied in SearchFunctionArguments
. These
exception classes are known to the CoreMedia Studio
integration provided as part of
CoreMedia Blueprint and are used to provide improved feedback to
CoreMedia Studio users in case they make any mistakes using search
functions.
Spring Configuration
The SearchFunctionPreprocessor
is intended to be configured as a Spring bean. It is thread safe so
using the default Spring singleton scope is fine.
Here is an example configuration that registers three search functions with the processor:
<bean class="com.coremedia.personalization.search. \ SearchFunctionPreprocessor"> <property name="functions"> <map> <entry key="userKeywords"> <bean class="com.coremedia.personalization. \ search.solr.SolrScoredKeys"> <property name="defaultLimit" value="5"/> <property name="defaultThreshold" value="0"/> <property name="defaultContextName" value="keyword"/> <property name="defaultField" value="keywords"/> </bean> </entry> <entry key="userSegments"> <bean class="com.coremedia.personalization. \ search.solr.SolrSegments"/> </entry> <entry key="contextProperty"> <bean class="com.coremedia.personalization.search. \ solr.SolrGeneralProperty"/> </entry> </map> </property> </bean>