Spring-Managed HST Components

For information about integrating HST Container with other web application frameworks, see HST Container Integration with Other Web Application Frameworks.

Container-Level Support for Spring-Managed HST Components

Starting with brXM 11, the HST Container can reference HST Component beans managed by the Spring Framework ApplicationContext. Instead of instantiating a component class directly using the hst:componentclassname property, the container first checks if a corresponding Spring bean exists.

For example, consider the following HST Component configuration in the repository:

/content:
  jcr:primaryTYpe: hst:component
  hst:componentclassname: org.hippoecm.hst.demo.components.Search

In brXM 10.x and earlier, the HST Container instantiates the class specified by hst:componentclassname (such as org.hippoecm.hst.demo.components.Search).

From version 11 onward, the HST Container first queries its ComponentManager (which is backed by the Spring ApplicationContext) for a bean with the name matching the class name. If the bean is found, the container uses it. If not, it falls back to instantiating the class directly, as in previous versions.

Managing HST Component beans with Spring allows you to use Spring features such as aspect-oriented programming (AOP) for your components.

Example: Using Spring-Managed HST Components in the Hippo Test Suite

To see a working example, build and run the Hippo Test Suite project. The source code is available at Hippo Test Suite on GitHub.

After starting the example, navigate to Search in the left menu of the sample website (http://localhost:8080/site/search). This page demonstrates a search form implemented as a Spring-managed HST Component.

HST Component Class with Spring Annotations

The following example shows the Search HST Component class from the Hippo Test Suite:

components/src/main/java/org/hippoecm/hst/demo/components/Search.java

package org.hippoecm.hst.demo.components;

import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.context.annotation.Scope;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;

/**
 * This HstComponent must be annotated with {@link Service}.
 * <P>
 * Note: HstComponent bean must always be {@link ConfigurableBeanFactory.SCOPE_PROTOTYPE} like this example.
 * Otherwise, thread-safety issue can occur due to a singleton bean instance of HstComponent.
 * In this example, the bean name (set by {@link Service} annotation) is set to the FQCN of this component class
 * because the component classname (as configured by @hst:componentclassname property) can be scanned for component
 * parameters in many other locations (e.g, Channel Manager), unless you explicitly set the @hst:parametersinfoclassname
 * property which has been supported since v12.1.
 * </P>
 */
// If you skip the value in @Component annotation, the logical bean name will be a camel-cased simple class name: "search",
// which should be set to the @hst:componentclassname property instead of the FQCN.
@Component(DemoConstants.COMPONENT_BASE_PACKAGE + ".Search")
@Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) 
public class Search extends AbstractSearchComponent {
  // -->8-->8--
}

This class uses several Spring annotations to enable automatic component scanning:

  • @Component is required.
  • For Bloomreach Content versions earlier than 12.1, set the value of @Component to the fully qualified class name (FQCN), matching the @hst:componentclassname property. This ensures:
    • If you omit the value, you must set @hst:componentclassname to the auto-generated Spring bean name, which is the camel-cased simple class name (for example, searchComponent instead of org.example.components.SearchComponent).
    • Component parameter information cannot be automatically scanned if @hst:componentclassname does not contain the FQCN.
  • Starting with version 12.1, you can omit the value in @Component if:
    • You set @hst:componentclassname to the auto-generated Spring bean name (camel-cased simple class name).
    • You set the @hst:parametersinfoclassname property to specify the FQCN of the component parameters info interface. This property enables parameter scanning in the Experience manager.
  • The @Scope annotation is required and must be set to ConfigurableBeanFactory.SCOPE_PROTOTYPE. Using a singleton scope can cause thread-safety or parameter collision issues.

Note: The example above always uses the "prototype" scope. This allows multiple HST Component configurations to use separate instances from a single bean definition. If you must use the "singleton" scope, define a separate bean for each HST Component configuration by using different @hst:componentclassname values. This avoids thread-safety and parameter collision issues.

Enabling Spring Automatic Component Scanning

To enable Spring's automatic component scanning for HST Components, add the following configuration to an XML file in the site/components/src/main/resources/META-INF/hst-assembly/overrides/ directory. In the Hippo Test Suite, this is located at components/src/main/resources/hst-assembly/overrides/components.xml:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.1.xsd
                           http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-4.1.xsd">

  <!-- (HST)Components Annotation Scanning -->
  <context:component-scan base-package="org.hippoecm.hst.demo.components" />

  <-- SNIP -->

</beans>

When the HST Container and its ComponentManager initialize, Spring scans the specified package (org.hippoecm.hst.demo.components) and registers all detected beans. In this example, Spring registers a bean named org.hippoecm.hst.demo.components.Search. When the HST Container needs to use the Search component (as specified in the repository configuration), it retrieves the bean from the Spring context instead of instantiating the class directly.

Summary

From brXM 11 onward, the HST Container can use beans managed by the Spring Framework. The component configuration in the repository does not change: you still specify the class name in the hst:componentclassname property. The container first checks for a bean with this name in the ComponentManager (backed by the Spring ApplicationContext). If found, it uses the bean; otherwise, it creates a new instance as in previous versions.

To use Spring's automatic component scanning, annotate your component class with @Component and @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE). Enable scanning by adding a <context:component-scan base-package="..." /> entry in your bean assembly XML file.

Managing HST Component beans with Spring enables you to use features such as AOP. For working examples, see the Hippo Test Suite project.

Share Feedback
Page: /build/web-application/spring-managed-hst-components
Section: Build
Category *
Spring-Managed HST Components | Bloomreach Content Documentation