Spring-Managed HST Components - Enterprise Java Content management system - Hippo CMS

Spring-Managed HST Components

Since Hippo CMS 11, HST supports Spring Framework managed HST Component beans without having to use Spring Bean Bridge anymore.
Container Level Integration, a different pattern of integration, is also supported. See HST Container Integration with Other Web Application Frameworks for more information.

Container Level Support for Spring Framework Managed HST Components

Since Hippo CMS 11, HST Container can get a reference to an HST Component bean maintained by Spring Framework ApplicationContext and use the bean, instead of creating an object by itself from hst:componentclassname property value.

Suppose you have the following HST Component configuration in HST configurations in repository:

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

Until Hippo CMS 10.x, HST Container creates an object by the class name (org.hippoecm.hst.demo.components.Search in this example).

Since Hippo CMS 11, HST Container looks up its ComponentManager (internally backed by Spring Framework ApplicationContext) first to find a bean named by the class name (org.hippoecm.hst.demo.components.Search in this example). If a bean by the name is found, then HST Container uses the bean instead of creating a new object. If not found, it creates an HST Component object by itself like it does in Hippo CMS 10.x or earlier versions.

By letting Spring Framework maintain your HST Component beans, you may take advantage of many good features of Spring Framework such as AOP techniques on your HST Components.

How-to with A Simple Example in Hippo Test Suite

If you want to see a demo, build and run the demo in the Hippo Test Suite project. The example is available in our source repository: Hippo Test Suite.

Next, click on the Search link on the left menu of the example website (http://localhost:8080/site/search). You will see a page containing search forms.

HST Component Class with Spring Framework Annotations

For the search page, the following HST Component was implemented in the Hippo Test Suite project:

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--
}

The Search class now has several Spring Framework annotations. Those annotations are needed when you want to take advantage of Spring Framework Automatic Component Scanning feature:

  • @Component annotation is required.
  • In the earlier versions than Hippo CMS 12.1, the value of @Component annotation should be set to the FQCN of the component class (which is the same as @hst:componentclassname property value) for the following reasons:
    • If the value is skipped, you must set @hst:componentclassname property to the auto-generated logical Spring bean name, a camel-cased simple class name. e.g, "searchComponent" instead of "org.example.components.SearchComponent".
    • The component parameters information cannot be automatically scanned (while using Channel Manager for instance) because @hst:componentclassname property value doesn't have a FQCN value.
  • Since Hippo CMS 12.1, you may skip the value of @Component annotation in the following conditions:
    • You must set @hst:componentclassname property to the auto-generated logical Spring bean name, a camel-cased simple class name. e.g, "searchComponent" instead of "org.example.components.SearchComponent".
    • You should set @hst:parametersinfoclassname property (since v12.1) to specify the FQCN of the component parameters info interface (which is equivalent to the type attribute of org.hippoecm.hst.core.parameters.ParametersInfo annotation in the component class. So, the component parameters info can be scanned by the new @hst:parametersinfoclassname property value if needed (while using Channel Manager for instance).
  • @Scope annotation is required and it must be set to ConfigurableBeanFactory.SCOPE_PROTOTYPE. Otherwise, you could meet severe thread-safety issues or parameter collision issues.
NOTE: Again, the Search HST Component example shown above is always scoped to "prototype". By scoping the bean as "prototype", you can set multiple HST Component configurations with different instances to share single bean definition. If you really have to use "singleton" (default) scoped bean for some reason, then add a different bean definition per HST Component configuration using different @hst:componentclassname property values, in order to avoid potential thread-safety issues or parameter collision issues between different component configurations.

Enabling Spring Framework Automatic Component Scanning

Now, we need to enable Spring Framework Automatic Component Scanning in initializing HST Container Component Manager. You can simply add the following in an XML file under site/src/main/resources/META-INF/hst-assembly/overrides/ folder. In the Hippo Test Suite project, it is included in 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 HST Container and its ComponentManager are initialized, Spring Framework will scan all the available components under the package org.hippoecm.hst.demo.components and register all the scanned beans. In this specific example, it will register a bean named org.hippoecm.hst.demo.components.Search, and later when HST Container needs to invoke the Search HST Component (as configured in the component configuration in the repository), it simply gets a reference to the existing bean instead of creating a new object by the class name by itself.

Summary

Since Hippo CMS 11, HST Container can get a reference to a bean maintained by Spring Framework, instead of creating an object by itself. In the perspective of HST Component configurations in the repository, there is no change from the traditional way of configuring component class name with hst:componentclassname property value. However, HST Container looks up a bean by the hst:componentclassname property value first from the ComponentManager (backed by Spring Framework ApplicationContext). If found, it simply uses the bean. Otherwise, it creates a new object like it does in CMS 10 or earlier versions.

When you want to take advantage of Spring Framework Automatic Component Scanning feature, you should use @Component and @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) annotations and enable the automatic scanning by adding <context:component-scan base-package="..." /> in an overriding bean assembly XML file.

By letting Spring Framework maintain your HST Component beans, you may take advantage of many good features of Spring Framework such as AOP techniques on your HST Components. See the examples in the Hippo Test Suite project for more detail.

Spring-Managed HST Components

Since Hippo CMS 11, HST supports Spring Framework managed HST Component beans without having to use Spring Bean Bridge anymore.
Container Level Integration, a different pattern of integration, is also supported. See HST Container Integration with Other Web Application Frameworks for more information.

Container Level Support for Spring Framework Managed HST Components

Since Hippo CMS 11, HST Container can get a reference to an HST Component bean maintained by Spring Framework ApplicationContext and use the bean, instead of creating an object by itself from hst:componentclassname property value.

Suppose you have the following HST Component configuration in HST configurations in repository:

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

Until Hippo CMS 10.x, HST Container creates an object by the class name (org.hippoecm.hst.demo.components.Search in this example).

Since Hippo CMS 11, HST Container looks up its ComponentManager (internally backed by Spring Framework ApplicationContext) first to find a bean named by the class name (org.hippoecm.hst.demo.components.Search in this example). If a bean by the name is found, then HST Container uses the bean instead of creating a new object. If not found, it creates an HST Component object by itself like it does in Hippo CMS 10.x or earlier versions.

By letting Spring Framework maintain your HST Component beans, you may take advantage of many good features of Spring Framework such as AOP techniques on your HST Components.

How-to with A Simple Example in Hippo Test Suite

If you want to see a demo, build and run the demo in the Hippo Test Suite project. The example is available in our source repository: Hippo Test Suite.

Next, click on the Search link on the left menu of the example website (http://localhost:8080/site/search). You will see a page containing search forms.

HST Component Class with Spring Framework Annotations

For the search page, the following HST Component was implemented in the Hippo Test Suite project:

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--
}

The Search class now has several Spring Framework annotations. Those annotations are needed when you want to take advantage of Spring Framework Automatic Component Scanning feature:

  • @Component annotation is required.
  • In the earlier versions than Hippo CMS 12.1, the value of @Component annotation should be set to the FQCN of the component class (which is the same as @hst:componentclassname property value) for the following reasons:
    • If the value is skipped, you must set @hst:componentclassname property to the auto-generated logical Spring bean name, a camel-cased simple class name. e.g, "searchComponent" instead of "org.example.components.SearchComponent".
    • The component parameters information cannot be automatically scanned (while using Channel Manager for instance) because @hst:componentclassname property value doesn't have a FQCN value.
  • Since Hippo CMS 12.1, you may skip the value of @Component annotation in the following conditions:
    • You must set @hst:componentclassname property to the auto-generated logical Spring bean name, a camel-cased simple class name. e.g, "searchComponent" instead of "org.example.components.SearchComponent".
    • You should set @hst:parametersinfoclassname property (since v12.1) to specify the FQCN of the component parameters info interface (which is equivalent to the type attribute of org.hippoecm.hst.core.parameters.ParametersInfo annotation in the component class. So, the component parameters info can be scanned by the new @hst:parametersinfoclassname property value if needed (while using Channel Manager for instance).
  • @Scope annotation is required and it must be set to ConfigurableBeanFactory.SCOPE_PROTOTYPE. Otherwise, you could meet severe thread-safety issues or parameter collision issues.
NOTE: Again, the Search HST Component example shown above is always scoped to "prototype". By scoping the bean as "prototype", you can set multiple HST Component configurations with different instances to share single bean definition. If you really have to use "singleton" (default) scoped bean for some reason, then add a different bean definition per HST Component configuration using different @hst:componentclassname property values, in order to avoid potential thread-safety issues or parameter collision issues between different component configurations.

Enabling Spring Framework Automatic Component Scanning

Now, we need to enable Spring Framework Automatic Component Scanning in initializing HST Container Component Manager. You can simply add the following in an XML file under site/src/main/resources/META-INF/hst-assembly/overrides/ folder. In the Hippo Test Suite project, it is included in 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 HST Container and its ComponentManager are initialized, Spring Framework will scan all the available components under the package org.hippoecm.hst.demo.components and register all the scanned beans. In this specific example, it will register a bean named org.hippoecm.hst.demo.components.Search, and later when HST Container needs to invoke the Search HST Component (as configured in the component configuration in the repository), it simply gets a reference to the existing bean instead of creating a new object by the class name by itself.

Summary

Since Hippo CMS 11, HST Container can get a reference to a bean maintained by Spring Framework, instead of creating an object by itself. In the perspective of HST Component configurations in the repository, there is no change from the traditional way of configuring component class name with hst:componentclassname property value. However, HST Container looks up a bean by the hst:componentclassname property value first from the ComponentManager (backed by Spring Framework ApplicationContext). If found, it simply uses the bean. Otherwise, it creates a new object like it does in CMS 10 or earlier versions.

When you want to take advantage of Spring Framework Automatic Component Scanning feature, you should use @Component and @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) annotations and enable the automatic scanning by adding <context:component-scan base-package="..." /> in an overriding bean assembly XML file.

By letting Spring Framework maintain your HST Component beans, you may take advantage of many good features of Spring Framework such as AOP techniques on your HST Components. See the examples in the Hippo Test Suite project for more detail.