The HstRequestContext Object

The HstRequestContext is a central object in the HST framework. It provides access to key resources and APIs required for request processing. These include:

Repository context via getSession()
Content for the current request via getContentBean()
Root content for the current channel via getSiteContentBaseBean()
Page and component configuration context, as well as servlet context and configuration
Host, Mount, and SitemapItem matching information
Link and URL creation utilities
Search API via getQueryManager()
Content API via getObjectBeanManager()
Access to ServletContext and HttpServletRequest
Detection of CMS context requests
Additional request-related information

The HstRequestContext exists for the duration of a single HttpServletRequest and is shared by all HST components handling that request. Each HST component receives a new HstRequest and HstResponse instance for its lifecycle methods (doBeforeRender, doAction, doBeforeServeResource), but the HstRequestContext remains the same across all components for that request.

Accessing the HstRequestContext

There are two primary ways to obtain the HstRequestContext. The second method is preferred, as it is always available for any request processed by the HstFilter.

1. From the HstRequest

You can retrieve the context directly from an HstRequest instance:

HstRequest#getRequestContext();

2. Using the Static Getter

If you are working in a context where an HstRequest is not available—such as when building REST APIs, integrating with other web application frameworks, or in utility code—you can obtain the context using:

RequestContextProvider#get();

This method returns the HstRequestContext for the current thread's active request. It returns null if the thread is not processing an HST request.

3. In a Freemarker Template

In Freemarker templates, you can access the HstRequestContext using the hst:defineObjects tag:

<#assign hst=JspTaglibs["http://www.hippoecm.org/jsp/hst/core"]>
<@hst.defineObjects />

${hstRequestContext}

The defineObjects tag also exposes hstRequest, hstResponse, and hstResponseChildContentNames for use in Freemarker code.

Note: Most archetype-generated projects already include <@hst.defineObjects/> in htmlTags.ftl. If your template includes htmlTags.ftl (for example, <#include "../htmlTags.ftl">), the HstRequestContext is already available.

4. In a JSP

In JSPs, use <hst:defineObjects/> to make the HstRequestContext and related objects available, similar to Freemarker.

Example: Creating and Executing a Search Query

You can execute repository queries using APIs accessible through the HstRequestContext. The following example demonstrates how to create and execute a search:

HstRequestContext requestContext = RequestContextProvider.get();
HstQuery query = requestContext.getQueryManager().createQuery(scope, NewsBean.class);
HstQueryResult result = query.execute();

For additional search examples, see HST Search.

API Overview

The HstRequestContext interface provides methods to access the content bean for the current request and the site content base bean. The following operations are available to simplify content retrieval and querying:

/**
 * HstRequestContext provides repository content context
 * and page/components configuration context.
 * Also, HstRequestContext is shared among all the HstComponent windows in a
 * request lifecycle.
 */
public interface HstRequestContext {

    // SNIP
    /**
     * @return A {@link ContentBeansTool} instance, never <code>null</code>.
     * Note that the {@link ContentBeansTool} is a object shared by
     * multiple threads
     */
    ContentBeansTool getContentBeansTool();

    /**
     * @return the root content path for the
     * {@link org.hippoecm.hst.core.request.ResolvedMount} belonging to the current
     * {@link javax.servlet.http.HttpServletRequest}
     */
    String getSiteContentBasePath();

    /**
     * Returns the siteContentBaseBean {@link HippoBean} for this request.
     * After first retrieval, the bean is cached and
     * the same instance will be returned when calling
     * {@link #getSiteContentBaseBean()} multiple times. The backing jcr
     * {@link javax.jcr.Node} is fetched through jcr Session {@link #getSession()}
     * @return the {@link HippoBean} belonging to for {@link #getSiteContentBasePath()}
     */
    HippoBean getSiteContentBaseBean();

    /**
     * Returns the content {@link HippoBean} for this request. After first retrieval,
     * the content bean is cached and
     * the same instance will be returned when calling {@link #getContentBean()}
     * multiple times. The backing jcr
     * {@link javax.jcr.Node} is fetched through jcr Session {@link #getSession()}
     * @return <code>HippoBean</code> belonging to the
     * {@link org.hippoecm.hst.core.request.ResolvedSiteMapItem} or
     * <code>null</code> {@link HstSiteMapItem#getRelativeContentPath()} is <code>null</code>
     * or when there is no content (jcr node) to be found at
     * {@link org.hippoecm.hst.configuration.sitemap.HstSiteMapItem#getRelativeContentPath()}.
     */
    HippoBean getContentBean();

    /**
     * @return a <code>ObjectBeanManager</code> instance for the current
     * {@link HstRequestContext} backed by the {@link #getSession()}
     * @throws IllegalStateException if the application is unable to
     * provide a ObjectBeanManager
     */
    public ObjectBeanManager getObjectBeanManager() throws IllegalStateException;

    /**
     * @param session the {@link Session} to create this
     * {@link ObjectBeanManager} with
     * @return a <code>ObjectBeanManager</code> instance for the
     * current {@link HstRequestContext} backed by the
     * <code>session</code>
     * @throws IllegalStateException if the application is unable
     * to provide a ObjectBeanManager
     */
    public ObjectBeanManager getObjectBeanManager(Session session) throws IllegalStateException;

    /**
     * @return the {@link HstQueryManager} backed by the {@link #getSession()}
     * @throws IllegalStateException if the application is unable to provide a HstQueryManager
     */
    public HstQueryManager getQueryManager() throws IllegalStateException;

    /**
     * @param session the {@link Session} to create this {@link ObjectBeanManager} with
     * @return the {@link org.hippoecm.hst.content.beans.query.HstQueryManager} backed by the
     * <code>session</code>
     * @throws IllegalStateException if the application is unable to provide a HstQueryManager
     */
    public HstQueryManager getQueryManager(Session session) throws IllegalStateException;
}

You can also use the ContentBeansTool API, which provides access to core HST Content Beans APIs such as ObjectConverter and HstQueryManager:

HstRequestContext requestContext = RequestContextProvider.get();
ContentBeansTool contentBeansTool = requestContext.getContentBeansTool();

When you use ContentBeansTool to obtain an HstQueryManager or ObjectBeanManager, you receive a non-caching instance. In contrast, the versions provided by HstRequestContext use a caching ObjectConverter and are generally preferred. Use HstRequestContext#getObjectBeanManager() for a caching ObjectBeanManager unless you specifically require a non-caching instance.

The ContentBeansTool interface is defined as follows:

/**
 * ContentBeansTool
 * <P>
 * This interface is supposed to be provided to external application frameworks and codes.
 * They can normally access this component by invoking
 * <code>HttpServletRequest#getAttribute(ContentBeansTool.class.getName());</code>.
 * </P>
 */
public interface ContentBeansTool {

    /**
     * @return <code>ObjectConverter</code> which is shareed across all threads
     */
    public ObjectConverter getObjectConverter();

    /**
     * @return a new <code>ObjectBeanManager</code> instance for
     * the {@link Session} <code>session</code>
     * @throws IllegalStateException if the application is unable to provide a ObjectBeanManager
     * @see org.hippoecm.hst.core.request.HstRequestContext#getObjectBeanManager(Session)
     * to re-use a cached one for
     * the current request
     */
    public ObjectBeanManager createObjectBeanManager(Session session) throws IllegalStateException;

    /**
     * @param session
     * @return the {@link HstQueryManager} for <code>session</code>
     * @throws IllegalStateException if the application is unable
     * to provide a HstQueryManager
     * @see org.hippoecm.hst.core.request.HstRequestContext#getQueryManager(Session)
     * to re-use a cached one for
     * the current request
     */
    public HstQueryManager createQueryManager(Session session) throws IllegalStateException;

}

In summary, prefer using the APIs provided by HstRequestContext for caching behavior and optimal performance. Use the ContentBeansTool only when you require non-caching instances or when integrating with external frameworks.