Respond to a Before Delete Channel Event

Overview

This page describes how to execute custom logic when an administrator deletes a channel in Bloomreach Content.

When to Use

Implement a listener for the BeforeChannelDeleteEvent when you need to:

Perform additional validation before a channel is deleted.
Execute custom actions related to channel deletion, such as cleaning up associated content.
Prevent channel deletion if specific conditions are not met.

How It Works

When a user with administrator privileges deletes a channel that is marked as deletable, the Experience Manager publishes a BeforeChannelDeleteEvent on the HST internal event bus. You can subscribe to this event to implement custom checks or actions.

To prevent deletion, raise an exception in your event handler.
To perform additional actions (such as removing related content), make changes in the JCR session provided by the event. Do not persist these changes; the Experience Manager will persist all changes in a single transaction.

Implementation Steps

1. Register a Channel Delete Event Listener

Create a Spring bean for your event listener. For example, add the following configuration to site/components/src/main/resources/META-INF/hst-assembly/overrides/channel-listeners.xml:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd">

  <bean class="com.example.BeforeChannelDeleteEventListener" init-method="init" 
        destroy-method="destroy"/>

</beans>

2. Implement the Event Listener

Create a class that subscribes to the BeforeChannelDeleteEvent. Use the @Subscribe annotation to handle the event. If your custom checks fail, set an exception on the event object. To provide feedback to the user, set a concise userMessage parameter.

package com.example;

import java.util.HashMap;
import java.util.Map;
import javax.jcr.Session;

import org.hippoecm.hst.pagecomposer.jaxrs.api.BeforeChannelDeleteEvent;
import org.hippoecm.hst.pagecomposer.jaxrs.api.ChannelEventListenerRegistry;
import org.hippoecm.hst.pagecomposer.jaxrs.services.exceptions.ClientError;
import org.hippoecm.hst.pagecomposer.jaxrs.services.exceptions.ClientException;

import org.onehippo.cms7.services.eventbus.Subscribe;
import org.onehippo.cms7.services.hst.Channel;

public class BeforeChannelDeleteEventListener {
    @SuppressWarnings("UnusedDeclaration")
    public void init() {
        ChannelEventListenerRegistry.get().register(this);
    }

    @SuppressWarnings("UnusedDeclaration")
    public void destroy() {
        ChannelEventListenerRegistry.get().unregister(this);
    }

    @Subscribe
    public void onChannelDeleteEvent(BeforeChannelDeleteEvent event) {
        if (event.getException() != null) {
            return; // Another subscriber already set an exception
        }

        final Channel channel = event.getChannel();
        if (!doCustomChecksPass()) {
            // Provide a user-friendly error message
            final Map<String, String> parameterMap = new HashMap<>();
            parameterMap.put("userMessage", "Channel {{channel}} cannot be deleted");
            parameterMap.put("channel", channel.getName());
            final String techDetails = "...";
            event.setException(new ClientException(techDetails, ClientError.UNKNOWN, parameterMap));
            return;
        }

        final Session session = event.getRequestContext().getSession();
        doCustomActions(channel, session); // Do not persist changes here
    }
}

Notes:

If another subscriber has already set an exception, your handler should return without further processing.
Any changes to the JCR repository must be made using the session from the event, but do not call session.save(). The Experience Manager will persist all changes in a single transaction.

Abort a Delete Channel Action

To prevent a channel from being deleted, set an exception on the event object within your listener. This approach is useful if validation fails or required post-processing cannot complete. For more details, see Abort an Experience Manager Action.

Verification

Attempt to delete a channel as an administrator.
If your custom checks fail, confirm that the deletion is blocked and the user sees your userMessage.
If your custom actions succeed, verify that related content is processed as expected and all changes are persisted.