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>