The HstRequestContext object

The HstRequestContext is the most important HST framework object which provides access to

1. Repository context through getSession(),
2. Content for current request through getContentBean()
3. Root content for current channel through getSiteContentBaseBean()
4. Page/components configuration context, servlet context/config,
5. Matching information (Host, Mount, SitemapItem),
6. Link and URL creation facilities,
7. Search API through getQueryManager()
8. Content API through getObjectBeanManager()
9. ServletContext, HttpServletRequest
10. Whether the request is comes from CMS context
11. and more.

The HstRequestContext has the lifecycle of a single HttpServletRequest, and is shared among all HstComponents. Thus where the #doBeforeRender, #doAction and #doBeforeServeResource of HstComponents get invoked with a new HstRequest and HstResponse instance per HstComponent for a single HttpServletRequest/Response, the HstRequestContext is shared.

There are two way to get hold of the HstRequestContext. The second way is preferred as that one is always available for any request that gets processed by the HstFilter.

1. Getting hold of the HstRequestContext from the HstRequest:

HstRequest#getRequestContext();

2. Getting hold of the HstRequestContext through static getter:

When you are building REST api's with HST, delegate to other Web Application Frameworks, or just do not have a HstRequest available in your method, you get hold of the HstRequestContext through.

RequestContextProvider#get();

This returns the HstRequestContext for the current threads active request, and null if the request is not a HST request processing thread.

3. Getting hold of the HstRequestContext in a freemarker template

In your freemarker template you can get hold of the HstRequestContext via the hst:defineObjects tag : 

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

${hstRequestContext}

Next to the hstRequestContext the defineObjects tag also makes the hstRequest, hstResponse and  hstResponseChildContentNames available in freemarker code. 

4. Getting hold of the HstRequestContext in a jsp

Same as for freemarker but use <hst:defineObjects/> instead.

Example of creating and executing a search through the HstRequestContext

Finally, you can even execute queries by using the API components provided via HstRequestContext like the following example.

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

For more search example you can take a look at HST Search.

API

The HstRequestContext contains methods to access the content bean for the current request and the site content base bean for the current request.

Specifically, the following operations were added in HstRequestContext to support much easier content retrieval and queries.

/**
 * 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;
}

Also, you can use ContentBeansTool API component, which provides most of the HST Content Beans access API (e.g, ObjectConverter, HstQueryManager, etc.)

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

If you use the ContentBeansTool to get hold of a HstQueryManager or ObjectBeanManager, you get different ones than from the HstRequestContext. Namely, the ones from the HstRequestContext come with a caching ObjectConverter, and are in general much preferred above the non-caching ContentBeansTool#createObjectBeanManager/createQueryManager.

The ContentBeansTool interface is defined like this:

/**
 * 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;

}