Post-Processing a Matched Sitemap Item with SiteMapItemHandlers

When the HST resolves a URL to an hst:sitemapitem, it creates a request-specific ResolvedSiteMapItem instance. This instance wraps the immutable HST sitemap item. You can inject custom logic after a sitemap item is resolved by implementing post-processing. During post-processing, you can:

• Short-circuit the request
• Return a different ResolvedSiteMapItem (for example, based on the mapped document)
• Set cookies or response headers
• Modify request attributes

To implement post-processing, follow these steps:

1. Implement one or more custom HstSiteMapItemHandler classes.
2. Configure the sitemap item handlers in the configuration model.
3. Assign one or more sitemap item handlers to a sitemap item.

Implement a Custom HstSiteMapItemHandler

To post-process a matched sitemap item, implement the HstSiteMapItemHandler interface. The primary method to implement is process:

/**
 * @return a new or the original {@link ResolvedSiteMapItem}, or null
 * when the handler has already written the response and request processing should stop
 * @throws HstSiteMapItemHandlerException
 */
ResolvedSiteMapItem process(ResolvedSiteMapItem resolvedSiteMapItem,
                            HttpServletRequest request,
                            HttpServletResponse response)
                                    throws HstSiteMapItemHandlerException;
copy

• The resolvedSiteMapItem parameter is either the matched sitemap item or the result from a previous handler in the chain.
• You can configure multiple handlers for a sitemap item. Each handler's process method is called in sequence until one returns null.
• Returning null short-circuits request processing.
• You can return a new ResolvedSiteMapItem instance, which may wrap a different hst:sitemapitem or a decorated version of the original. For example, a decorated version might override getHstComponentConfiguration().

The handler also receives a SiteMapItemHandlerConfiguration instance via init(ServletContext servletContext, SiteMapItemHandlerConfiguration handlerConfig). See the next section for configuration details.

Configure Sitemap Item Handlers

Under your project's hst:configuration node, create a node named hst:sitemapitemhandlers. Define your sitemap item handlers as child nodes of this node. Each handler node:

• Can have any name.
• Must use the primary type hst:sitemapitemhandler.
• Must set the hst:sitemapitemhandlerclassname property to the fully qualified class name of your handler implementation.
• Can include additional configuration properties of type string, boolean, long, double, or date (single or multiple values).

These properties are available in your handler class through the init(ServletContext servletContext, SiteMapItemHandlerConfiguration handlerConfig) method.

The CND for hst:sitemapitemhandler is:

[hst:sitemapitemhandler] > nt:base, mix:referenceable
- hst:sitemapitemhandlerclassname (string) mandatory
- * (string)
- * (string) multiple
- * (boolean)
- * (boolean) multiple
- * (long)
- * (long) multiple
- * (double)
- * (double) multiple
- * (date)
- * (date) multiple 
copy

Assign Sitemap Item Handlers to a Sitemap Item

After configuring your handler nodes under hst:sitemapitemhandlers and implementing your handler classes, you can assign handlers to a sitemap item. Use the multivalued property hst:sitemapitemhandlerids on an hst:sitemapitem node. Each value is the node name of a handler under hst:sitemapitemhandlers.

If you specify multiple handlers in hst:sitemapitemhandlerids, their process methods are called in the order listed.

Example configuration:

/hst:sitemapitemhandlers:
  /set-pragma-no-cache-handler:
    hst:sitemapitemhandlerclassname: ...........
  /redirect-if-logged-in-handler:
    hst:sitemapitemhandlerclassname: ...........
copy

Assign handlers to a sitemap item:

/hst:sitemap:
  /bar:
    jcr:primaryType: hst:sitemapitem
  /foo:
    jcr:primaryType: hst:sitemapitem
    hst:sitemapitemhandlerids = [set-pragma-no-cache-handler, redirect-if-logged-in-handler] 
copy

In this example, the foo sitemap item will invoke the set-pragma-no-cache-handler and redirect-if-logged-in-handler in sequence after matching.

Using HstSiteMapItemHandler to Delegate Requests with FilterChain

A HstSiteMapItemHandler can delegate the request to another Servlet application by invoking javax.servlet.FilterChain and returning null from its process() method.

When HstFilter calls a configured HstSiteMapItemHandler for a sitemap item, and the handler calls FilterChain.doFilter() and returns null, HstFilter stops processing the request. The request is then delegated to another Servlet application.

To use this feature, extend org.hippoecm.hst.core.sitemapitemhandler.AbstractFilterChainAwareHstSiteMapItemHandler instead of directly implementing HstSiteMapItemHandler. Implement the following method:

/**
 * Performs custom request processing.
 *
 * This method can return the original or a new ResolvedSiteMapItem to continue processing,
 * or return null if it has completed custom processing (such as delegating to another Servlet).
 *
 * If you invoke filterChain.doFilter(..), you must return null to ensure HST rendering is stopped.
 *
 * @param resolvedSiteMapItem
 * @param request
 * @param response
 * @param filterChain
 * @return a new or the original ResolvedSiteMapItem, or null if processing should stop
 * @throws HstSiteMapItemHandlerException
 */
ResolvedSiteMapItem process(ResolvedSiteMapItem resolvedSiteMapItem,
                            HttpServletRequest request,
                            HttpServletResponse response,
                            FilterChain filterChain) throws HstSiteMapItemHandlerException;
copy

By using this approach, you can integrate custom routing or delegate processing to other Servlet applications as needed.