PingFilter

Why to use the PingFilter

Both the PingServlet and PingFilter typically are used by loadbalancers to find out whether a cluster node is available. When they return a status 200 (HttpServletResponse.SC_OK) it means the cluster node is ready to serve requests and the loadbalancer most likely will send some traffic to the cluster node. There is only a big difference in how a ping request is handled by the PingServlet and the PingFilter, see below.  It is always better to use the PingFilter instead of the PingServlet, but if you have an extremely large HST configuration, it is much better to use the PingFilter because as opposed to the PingServlet, the PingFilter always returns instantly with a response. 

The reason why by default we still bootstrap a project with the PingServlet is for backwards compatibilty reasons.

Difference PingFilter/PingServlet

The PingServlet in the site webapp only returns after the repository has been completely initialised and up & running and the entire HST in memory model has been loaded and build. In case you have a gigantic HST configuration (for example containing 100.000 configuration JCR nodes), the initial load of the model can take a considerable time since every JCR Node needs to be fetched from the database right after startup (since not yet present in the bundle cache). Assuming 1 ms per database fetch results in the first ping request to take at least 100 seconds (for just fetching the configuration nodes). During this 100 seconds, the loadbalancer can already decide the cluster node is not available and drop it again. 

Opposed to the  PingServlet, the PingFilter returns instantly, either with a status 200 (HttpServletResponse.SC_OK) meaning the loadbalancer can start sending traffic to the cluster node, or with a 503 (HttpServletResponse.SC_SERVICE_UNAVAILABLE) meaning the cluster node is not yet ready to serve requests. After more pings to the  PingFilter, after some time, the 503 changes into status 200 meaning the application is ready to serve requests.

Prerequisite 

If you want to use the PingFilter setup in CMS 11.2.8+, in the site web.xml you need to include the following context parameters configuration:

  <context-param>
    <param-name>hst-lazy-configuration-loading</param-name>
    <param-value>false</param-value>
  </context-param>

  <context-param>
    <param-name>hst-wait-for-repository-to-start</param-name>
    <param-value>true</param-value>
  </context-param>

Note that if you are in your CMS 11.2 project also using a Spring Root WebApplicationContext that also needs access to HST Spring Component beans, then you also need to replace  

  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>

with

  <listener>
    <listener-class>org.hippoecm.hst.site.container.HstDelayedContextLoaderListener</listener-class>
  </listener>

Also see Using Spring Root WebApplicationContext in HST.

Configure the PingFilter in the site webapp

In the HST site webapp(s) web.xml add the PingFilter before the HstFilter

<filter>
  <filter-name>PingFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.PingFilter</filter-class>
</filter>

and filter-mapping (before the HstFilter mapping)

<filter-mapping>
  <filter-name>PingFilter</filter-name>
  <url-pattern>/ping/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>

and if present remove the PingServlet 

<servlet>
  <servlet-name>PingServlet</servlet-name>
  <servlet-class>org.hippoecm.hst.servlet.HstPingServlet</servlet-class>
</servlet>

and its mapping

<servlet-mapping>
  <servlet-name>PingServlet</servlet-name>
  <url-pattern>/ping/*</url-pattern>
</servlet-mapping>

Now, ping requests, for example http://www.example.org/ping are handled by the PingFilter instead of the PingServlet.