Event Migration

Event Migration — AEM as a Cloud Service

Overview

org.osgi.service.event.EventHandler is the API for reacting to non-resource OSGi Event Admin events on AEM CS — replication events (com.day.cq.replication.ReplicationEvent.EVENT_TOPIC), workflow events (com/adobe/granite/workflow/*), and custom inter-bundle event topics. The handler runs on a shared OSGi event thread and must stay lightweight — all business logic must be offloaded to a Sling Job via JobManager.addJob().

Three CS-specific constraints every event handler must satisfy:

handleEvent() runs synchronously on a shared OSGi thread. Doing repository, network, or workflow work inline blocks event delivery for every other handler subscribed to anything. Always offload to a JobConsumer.

Routing — is this the right skill?

Use this skill when the source listens to a non-resource OSGi Event Admin topic:

Route elsewhere when:

Do not subscribe a new EventHandler to org/apache/sling/api/resource/Resource/ADDED|CHANGED|REMOVED. Those topics are an internal Sling dispatcher detail, deprecated as an application-facing API. Use ResourceChangeListener for resource observation.

Where to find topic constants

Always subscribe via a documented topic constant — never invent or copy-paste a topic string. The canonical constants live in the producing bundle's API:

A typo'd topic string compiles fine and silently subscribes to a topic that nothing posts to — the handler is ACTIVE but never fires. Reference the constant in code instead of duplicating the literal string.

Classification — choose before making any changes

Implements EventHandler for a non-resource topic and handleEvent() only enqueues jobs → Already compliant — verify against the Review Checklist only.

Implements EventHandler for a non-resource topic and handleEvent() contains business logic (resolver, JCR ops, heavy processing) → Apply E1–E5.

Implements javax.jcr.observation.EventListener for a concern that cannot be expressed as a ResourceChangeListener (rare — most legacy JCR listeners should route to the resource-change-listener skill) → Apply E0 (convert to EventHandler for the appropriate non-resource topic) then E1–E5. If unsure whether RCL covers it, prefer RCL and ask before falling through to this skill.

One pattern per session. If the bundle has multiple legacy handlers, migrate one class at a time.

Before starting: Read ../references/aem-cloud-service-pattern-prerequisites.md and apply SCR→DS, service-user, and SLF4J fixes if present in the same changeset.

Discovery

Detection is performed by the analyzer (../scripts/analyze.sh), run by the runbook:

bash ../scripts/analyze.sh <workspace-root> --pattern event-migration

Match criteria (what the detector flags): a class that implements org.osgi.service.event.EventHandler or javax.jcr.observation.EventListener (import-aware) — both map here per the BPA subtype taxonomy.

Emitted at the class declaration, with the class header as the snippet. Parse-level only — direct implements clause; the subscribed topic (resource vs non-resource) is not resolved at detection, so topic-based routing to resource-change-listener happens during remediation (see Routing / Classification). A class implementing both an event interface and ResourceChangeListener is flagged by both patterns (rare).

Resolution contract

guided — apply (guided). The analyzer locates each handler/listener; remediation is judgment-based and applied via E0–E5 (per the Classification above) in an apply session. Rows are evaluated top-down — first match wins, so resource/content observation routes to resource-change-listener before the E0 fall-through is considered.

Complete example — before and after

Before (replication EventHandler with inline business logic)

package com.example.listeners;

import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Reference;
import org.apache.sling.api.resource.ModifiableValueMap;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.api.resource.ResourceResolverFactory;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;
import com.day.cq.replication.ReplicationAction;
import com.day.cq.replication.ReplicationActionType;
import com.day.cq.replication.ReplicationEvent;

import java.util.Calendar;
import java.util.Collections;

@Component(
    immediate = true,
    property = {
        EventConstants.EVENT_TOPIC + "=com/day/cq/replication"
    }
)
public class ReplicationDateEventHandler implements EventHandler {

    @Reference
    private ResourceResolverFactory resolverFactory;

    @Override
    public void handleEvent(Event event) {
        try {
            ReplicationAction action = ReplicationEvent.fromEvent(event).getReplicationAction();
            if (action.getType() == ReplicationActionType.ACTIVATE) {
                ResourceResolver resolver = resolverFactory.getServiceResourceResolver(
                        Collections.singletonMap(ResourceResolverFactory.SUBSERVICE, "replication-service"));
                Resource resource = resolver.getResource(action.getPath() + "/jcr:content");
                if (resource != null) {
                    ModifiableValueMap map = resource.adaptTo(ModifiableValueMap.class);
                    map.put("cq:lastReplicated", Calendar.getInstance());
                    resolver.commit();
                }
                resolver.close();
            }
        } catch (Exception e) {
            System.err.println("Error updating replication date: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

After — Cloud Service compatible

File 1 — ReplicationDateEventHandler.java (lightweight EventHandler + leader election)

package com.example.listeners;

import org.apache.sling.discovery.TopologyEvent;
import org.apache.sling.discovery.TopologyEventListener;
import org.apache.sling.event.jobs.JobManager;
import org.osgi.framework.Constants;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;
import com.day.cq.replication.ReplicationAction;
import com.day.cq.replication.ReplicationActionType;
import com.day.cq.replication.ReplicationEvent;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.HashMap;
import java.util.Map;

@Component(
    service = { EventHandler.class, TopologyEventListener.class },
    immediate = true,
    property = {
        Constants.SERVICE_DESCRIPTION + "=Update lastReplicated on activation",
        EventConstants.EVENT_TOPIC + "=com/day/cq/replication"
    }
)
public class ReplicationDateEventHandler implements EventHandler, TopologyEventListener {

    public static final String JOB_TOPIC = "com/example/replication/date/update";

    private static final Logger LOG = LoggerFactory.getLogger(ReplicationDateEventHandler.class);
    private volatile boolean isLeader = false;

    @Reference
    private JobManager jobManager;

    @Override
    public void handleTopologyEvent(TopologyEvent event) {
        if (event.getType() == TopologyEvent.Type.TOPOLOGY_CHANGED
                || event.getType() == TopologyEvent.Type.TOPOLOGY_INIT) {
            isLeader = event.getNewView().getLocalInstance().isLeader();
            LOG.info("Topology updated; isLeader={}", isLeader);
        }
    }

    @Override
    public void handleEvent(Event event) {
        if (!isLeader) {
            return;
        }
        try {
            ReplicationAction action = ReplicationEvent.fromEvent(event).getReplicationAction();
            if (action.getType() != ReplicationActionType.ACTIVATE) {
                return;
            }
            Map<String, Object> jobProperties = new HashMap<>();
            jobProperties.put("path", action.getPath());
            jobManager.addJob(JOB_TOPIC, jobProperties);
        } catch (Exception e) {
            LOG.error("Failed to enqueue replication-date job", e);
        }
    }
}

File 2 — ReplicationDateJobConsumer.java (business logic runs here, with a service-user resolver)

package com.example.listeners;

import org.apache.sling.api.resource.LoginException;
import org.apache.sling.api.resource.ModifiableValueMap;
import org.apache.sling.api.resource.PersistenceException;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.api.resource.ResourceResolverFactory;
import org.apache.sling.event.jobs.Job;
import org.apache.sling.event.jobs.consumer.JobConsumer;
import org.apache.sling.event.jobs.consumer.JobResult;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Calendar;
import java.util.Collections;

@Component(
    service = JobConsumer.class,
    property = {
        JobConsumer.PROPERTY_TOPICS + "=com/example/replication/date/update"
    }
)
public class ReplicationDateJobConsumer implements JobConsumer {

    private static final Logger LOG = LoggerFactory.getLogger(ReplicationDateJobConsumer.class);
    private static final String SUBSERVICE = "event-handler-service";

    @Reference
    private ResourceResolverFactory resolverFactory;

    @Override
    public JobResult process(final Job job) {
        final String path = job.getProperty("path", String.class);
        if (path == null) {
            LOG.warn("Job missing 'path' property; CANCEL");
            return JobResult.CANCEL;
        }

        try (ResourceResolver resolver = resolverFactory.getServiceResourceResolver(
                Collections.singletonMap(ResourceResolverFactory.SUBSERVICE, SUBSERVICE))) {

            Resource resource = resolver.getResource(path + "/jcr:content");
            if (resource != null) {
                ModifiableValueMap map = resource.adaptTo(ModifiableValueMap.class);
                map.put("cq:lastReplicated", Calendar.getInstance());
                resolver.commit();
                LOG.debug("Updated lastReplicated for {}", path);
            }
            return JobResult.OK;

        } catch (LoginException e) {
            LOG.error("Could not open service resolver for '{}'", SUBSERVICE, e);
            return JobResult.FAILED;
        } catch (PersistenceException e) {
            LOG.error("Failed to commit lastReplicated for {}", path, e);
            return JobResult.FAILED;
        }
    }
}

Required Repoinit (in ui.config):

create service user event-handler-service

set ACL for event-handler-service
    allow jcr:read,rep:write on /content
end

Required service-user mapping (ui.config, file named e.g. org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended-event-handler.cfg.json):

{
  "user.mapping": [
    "com.example.mybundle:event-handler-service=[event-handler-service]"
  ]
}

Use the amend form (ServiceUserMapperImpl.amended-<name>.cfg.json) and the principal-name mapping (square-bracket form =[service-user-name]). Do not use the deprecated userName form. Permissions must be declared directly on the service user — do not rely on group inheritance.

Variant — workflow events

Workflow events live on topics under com/adobe/granite/workflow/* and expose payload properties via com.adobe.granite.workflow.event.WorkflowEvent constants. The overall shape (lightweight handler + leader election + JobConsumer) is identical to the replication example — only the topic, the event-type discriminator, and the payload keys change. Full standalone handler:

package com.example.listeners;

import com.adobe.granite.workflow.event.WorkflowEvent;
import org.apache.sling.discovery.TopologyEvent;
import org.apache.sling.discovery.TopologyEventListener;
import org.apache.sling.event.jobs.JobManager;
import org.osgi.framework.Constants;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.HashMap;
import java.util.Map;

@Component(
    service = { EventHandler.class, TopologyEventListener.class },
    immediate = true,
    property = {
        Constants.SERVICE_DESCRIPTION + "=Handle workflow completion",
        EventConstants.EVENT_TOPIC + "=com/adobe/granite/workflow/event"
    }
)
public class WorkflowCompletedEventHandler implements EventHandler, TopologyEventListener {

    public static final String JOB_TOPIC = "com/example/workflow/completed";

    private static final Logger LOG = LoggerFactory.getLogger(WorkflowCompletedEventHandler.class);
    private volatile boolean isLeader = false;

    @Reference
    private JobManager jobManager;

    @Override
    public void handleTopologyEvent(TopologyEvent event) {
        if (event.getType() == TopologyEvent.Type.TOPOLOGY_CHANGED
                || event.getType() == TopologyEvent.Type.TOPOLOGY_INIT) {
            isLeader = event.getNewView().getLocalInstance().isLeader();
        }
    }

    @Override
    public void handleEvent(Event event) {
        if (!isLeader) {
            return;
        }
        try {
            String eventType = (String) event.getProperty(WorkflowEvent.EVENT_TYPE);
            if (!WorkflowEvent.WORKFLOW_COMPLETED_EVENT.equals(eventType)) {
                return;
            }
            Map<String, Object> jobProperties = new HashMap<>();
            jobProperties.put("workflowId", event.getProperty(WorkflowEvent.WORKFLOW_ID));
            jobProperties.put("workItemId", event.getProperty(WorkflowEvent.WORK_ITEM));
            jobProperties.put("path", event.getProperty("path"));
            jobManager.addJob(JOB_TOPIC, jobProperties);
        } catch (Exception e) {
            LOG.error("Failed to enqueue workflow-completed job", e);
        }
    }
}

Common WorkflowEvent payload keys:

The JobConsumer pattern is unchanged from the replication example — read the properties via job.getProperty("key", Type.class) and apply the business logic.

E0 — Convert legacy javax.jcr.observation.EventListener to EventHandler (rare)

Apply only when the legacy EventListener observes a concern that cannot be expressed as a ResourceChangeListener. The default route for JCR observation is the resource-change-listener skill — fall through to E0 only after confirming the use case is non-resource.

// BEFORE — JCR Observation
import javax.jcr.observation.Event;
import javax.jcr.observation.EventListener;
import javax.jcr.observation.EventIterator;

public class MyListener implements EventListener {
    @Override
    public void onEvent(EventIterator events) {
        while (events.hasNext()) { /* ... */ }
    }
}

// AFTER — OSGi EventHandler on a non-resource topic
import org.osgi.framework.Constants;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;

@Component(
    service = EventHandler.class,
    immediate = true,
    property = {
        Constants.SERVICE_DESCRIPTION + "=My handler",
        EventConstants.EVENT_TOPIC + "=com/example/my/topic"
    }
)
public class MyEventHandler implements EventHandler {
    @Override
    public void handleEvent(Event event) { /* enqueue job — see E2 */ }
}

Pick the topic from the producing bundle's documented OSGi event topics — do not invent topics. If you cannot find a documented non-resource topic that matches the legacy intent, the use case probably is a resource observation and belongs in the resource-change-listener skill.

E1 — Make handleEvent() lightweight; offload to Sling Job

For production AEMaaCS code, the recommended pattern is:

1. Inspect the event for the data you need (path, action type, properties)
2. Apply minimal filtering (e.g. ReplicationActionType.ACTIVATE only)
3. Build a job payload (Map<String, Object>)
4. Call jobManager.addJob(JOB_TOPIC, props)
5. Return immediately

Repository access, service resolver creation, workflow operations, replication API calls, external API calls, and other expensive work belong in a JobConsumer — never inside handleEvent().

@Override
public void handleEvent(Event event) {
    try {
        String path = (String) event.getProperty("path");
        Map<String, Object> jobProperties = new HashMap<>();
        jobProperties.put("path", path);
        jobManager.addJob(JOB_TOPIC, jobProperties);
    } catch (Exception e) {
        LOG.error("Failed to enqueue job for event {}", event.getTopic(), e);
    }
}

Wrap the body in try/catch. A thrown exception from handleEvent() does not abort the OSGi event-admin dispatcher, but it bypasses your normal error handling and pollutes the OSGi logs with framework-level stack traces. Always log and continue.

Subscribing to multiple topics or wildcards

The EVENT_TOPIC property accepts an array of topics, and Sling supports a trailing /* wildcard to subscribe to a topic hierarchy:

// Multiple specific topics in one handler:
property = {
    EventConstants.EVENT_TOPIC + "=com/adobe/granite/workflow/event",
    EventConstants.EVENT_TOPIC + "=com/day/cq/replication"
}

// All workflow events via wildcard:
property = {
    EventConstants.EVENT_TOPIC + "=com/adobe/granite/workflow/*"
}

When subscribing to multiple topics or a wildcard, handleEvent() must inspect event.getTopic() to know which topic fired and dispatch accordingly:

@Override
public void handleEvent(Event event) {
    if (!isLeader) {
        return;
    }
    String topic = event.getTopic();
    if (topic.startsWith("com/adobe/granite/workflow/")) {
        enqueueWorkflowJob(event);
    } else if (ReplicationEvent.EVENT_TOPIC.equals(topic)) {
        enqueueReplicationJob(event);
    }
}

Prefer one handler per topic when the handler logic differs significantly — a wildcard handler that grew a long if/else chain is a refactor signal.

E2 — Create the JobConsumer (business logic)

Create a new class that moves all the business logic from handleEvent() into process(Job):

@Component(
    service = JobConsumer.class,
    property = {
        JobConsumer.PROPERTY_TOPICS + "=com/example/your/topic"
    }
)
public class YourJobConsumer implements JobConsumer {

    private static final Logger LOG = LoggerFactory.getLogger(YourJobConsumer.class);

    @Reference
    private ResourceResolverFactory resolverFactory;

    @Override
    public JobResult process(final Job job) {
        final String path = job.getProperty("path", String.class);

        try (ResourceResolver resolver = resolverFactory.getServiceResourceResolver(
                Collections.singletonMap(ResourceResolverFactory.SUBSERVICE, "event-handler-service"))) {
            // business logic
            return JobResult.OK;
        } catch (LoginException e) {
            LOG.error("Could not open service resolver", e);
            return JobResult.FAILED;
        }
    }
}

Rules:

• Topic on the JobConsumer component must match the topic used in jobManager.addJob. Share the topic as a static final String referenced by both classes.
• Move all business @Reference fields (ResourceResolverFactory, domain services) to the JobConsumer.
• Extract job data via job.getProperty("key", Type.class) — never the deprecated JobUtil.getProperty(...).
• Return JobResult.OK on success, JobResult.FAILED on retryable failure, JobResult.CANCEL for unrecoverable failures (missing required job property, permission denied with no retry path).
• getServiceResourceResolver throws LoginException on failure — it does not normally return null. Catch LoginException; do not add a resolver == null branch unless a custom wrapper is in use.

Write-side consumers — resolver.commit() is mandatory: If process() modifies JCR content, call resolver.commit() before the try-with-resources closes the resolver. Without it, changes are silently discarded. Catch PersistenceException separately.

E3 — TopologyEventListener for leader-only execution

In AEMaaCS author clusters, an OSGi event posted by one node may be delivered to every author pod. For side-effecting handlers (writing back to the repo, triggering replication, sending notifications), enqueueing the job from every pod produces N duplicate jobs.

TopologyEventListener is the supported way to elect a single leader and gate execution:

@Component(
    service = { EventHandler.class, TopologyEventListener.class },
    immediate = true,
    property = {
        EventConstants.EVENT_TOPIC + "=" + ReplicationEvent.EVENT_TOPIC
    }
)
public class LeaderOnlyHandler implements EventHandler, TopologyEventListener {

    private volatile boolean isLeader = false;

    @Override
    public void handleTopologyEvent(TopologyEvent event) {
        if (event.getType() == TopologyEvent.Type.TOPOLOGY_CHANGED
                || event.getType() == TopologyEvent.Type.TOPOLOGY_INIT) {
            isLeader = event.getNewView().getLocalInstance().isLeader();
        }
    }

    @Override
    public void handleEvent(Event event) {
        if (!isLeader) {
            return;
        }
        // enqueue job
    }
}

Add TopologyEventListener when:

• The handler subscribes to a topic that is fan-out delivered across the cluster (replication, workflow lifecycle, custom topics emitted on each node)
• The downstream action must execute exactly once per logical event (write back to repo, trigger external system, send notification, replicate)
• The original legacy code had any isLeader() / isMaster() / "only run on one instance" logic

Skip TopologyEventListener when:

• The handler reads ephemeral local state (per-pod metrics, local cache update)
• The downstream action is genuinely idempotent at the data layer (every pod doing the same write produces the same final state)
• The topic is delivered only to one node by design (rare for OSGi Event Admin — verify before assuming)

A simple SlingSettingsService.getRunModes().contains("author") check is not enough. Run-mode tells you author vs publish; it does not elect one author pod over another. For singleton execution on author, use TopologyEventListener.

E4 — Update imports

EventHandler class — Remove:

import org.apache.felix.scr.annotations.*;
import org.apache.sling.api.resource.ResourceResolverFactory;  // moves to JobConsumer
import javax.jcr.observation.Event;                            // only if migrating from JCR
import javax.jcr.observation.EventListener;                    // only if migrating from JCR
import javax.jcr.observation.EventIterator;                    // only if migrating from JCR

EventHandler class — Add:

import org.osgi.framework.Constants;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;
import org.apache.sling.event.jobs.JobManager;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.HashMap;
import java.util.Map;
// For leader-only handlers:
import org.apache.sling.discovery.TopologyEvent;
import org.apache.sling.discovery.TopologyEventListener;

JobConsumer class — Add:

import org.apache.sling.api.resource.LoginException;
import org.apache.sling.api.resource.PersistenceException;  // only if writing
import org.apache.sling.api.resource.Resource;              // only if writing
import org.apache.sling.api.resource.ModifiableValueMap;    // only if writing
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.api.resource.ResourceResolverFactory;
import org.apache.sling.event.jobs.Job;
import org.apache.sling.event.jobs.consumer.JobConsumer;
import org.apache.sling.event.jobs.consumer.JobResult;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.Collections;

E5 — Repoinit and service-user mapping

The JobConsumer acquires a resolver via SUBSERVICE. On AEM as a Cloud Service, the backing system user must be created via Repoinit (the repo-init OSGi factory config) and mapped through ServiceUserMapperImpl.amended. The classic UI-based user admin is not available.

Repoinit (in ui.config):

create service user event-handler-service

set ACL for event-handler-service
    allow jcr:read on /content
    allow jcr:read,rep:write on /var/my-app
end

ServiceUserMapperImpl.amended-<bundle>.cfg.json:

{
  "user.mapping": [
    "com.example.mybundle:event-handler-service=[event-handler-service]"
  ]
}

Mapping conventions:

• Use the amend form — do not edit the base ServiceUserMapperImpl config
• Use principal-name mapping: the square-bracket form =[service-user-name]
• Do not use the deprecated userName form
• Bundle symbolic name on the left of : must match the bundle owning the JobConsumer
• Permissions must be declared directly on the service user — do not rely on group inheritance

See ../references/aem-cloud-service-pattern-prerequisites.md for the full Repoinit workflow.

Greenfield — writing a new EventHandler from scratch

When writing a new handler for a non-resource topic (not migrating legacy), use this template. It bundles the AEMaaCS best practices into one self-contained pair: lightweight handler, optional leader election, JobConsumer with proper outcome classification.

// File 1: lightweight EventHandler with optional leader election
@Component(
    service = { EventHandler.class, TopologyEventListener.class },
    immediate = true,
    property = {
        Constants.SERVICE_DESCRIPTION + "=My custom event handler",
        EventConstants.EVENT_TOPIC + "=com/example/custom/topic"
    }
)
public class MyEventHandler implements EventHandler, TopologyEventListener {

    public static final String JOB_TOPIC = "com/example/custom/job";

    private static final Logger LOG = LoggerFactory.getLogger(MyEventHandler.class);
    private volatile boolean isLeader = false;

    @Reference
    private JobManager jobManager;

    @Override
    public void handleTopologyEvent(TopologyEvent event) {
        if (event.getType() == TopologyEvent.Type.TOPOLOGY_CHANGED
                || event.getType() == TopologyEvent.Type.TOPOLOGY_INIT) {
            isLeader = event.getNewView().getLocalInstance().isLeader();
        }
    }

    @Override
    public void handleEvent(Event event) {
        if (!isLeader) {
            return;
        }
        try {
            String path = (String) event.getProperty("path");
            if (path == null) {
                return;
            }
            Map<String, Object> jobProperties = new HashMap<>();
            jobProperties.put("path", path);
            jobManager.addJob(JOB_TOPIC, jobProperties);
        } catch (Exception e) {
            LOG.error("Failed to enqueue job", e);
        }
    }
}

// File 2: JobConsumer with outcome classification
@Component(
    service = JobConsumer.class,
    property = { JobConsumer.PROPERTY_TOPICS + "=com/example/custom/job" }
)
public class MyJobConsumer implements JobConsumer {

    private static final Logger LOG = LoggerFactory.getLogger(MyJobConsumer.class);
    private static final String SUBSERVICE = "my-event-handler-service";

    @Reference
    private ResourceResolverFactory resolverFactory;

    @Override
    public JobResult process(final Job job) {
        final String path = job.getProperty("path", String.class);
        if (path == null) {
            return JobResult.CANCEL;  // unrecoverable — required property missing
        }

        try (ResourceResolver resolver = resolverFactory.getServiceResourceResolver(
                Collections.singletonMap(ResourceResolverFactory.SUBSERVICE, SUBSERVICE))) {
            // business logic; resolver.commit() if writing
            return JobResult.OK;
        } catch (LoginException e) {
            LOG.error("Could not open service resolver", e);
            return JobResult.FAILED;  // retryable
        }
    }
}

What this template captures:

• Leader-only by default — drop the TopologyEventListener parts only if you've verified the action is genuinely idempotent or per-node intentional
• Topic shared as a static final String — never copy the literal into the consumer's PROPERTY_TOPICS
• JobResult outcomes mapped deliberately — CANCEL for missing required job data (won't recover on retry), FAILED for transient errors (Sling will retry), OK for success

Composition — EventHandler → JobConsumer → Distributor

A common production pattern is reacting to a replication event by triggering follow-up distribution (e.g. mirror the activation to a preview tier, or republish dependent content). The composition is straightforward: the EventHandler enqueues a job; the consumer calls Distributor.distribute(...). Full consumer:

@Override
public JobResult process(final Job job) {
    final String path = job.getProperty("path", String.class);
    if (path == null) {
        return JobResult.CANCEL;
    }

    try (ResourceResolver resolver = resolverFactory.getServiceResourceResolver(
            Collections.singletonMap(ResourceResolverFactory.SUBSERVICE, SUBSERVICE))) {

        DistributionRequest request = new SimpleDistributionRequest(
                DistributionRequestType.ADD, false, path);
        DistributionResponse response = distributor.distribute("preview", resolver, request);

        if (response.isSuccessful()) {
            return JobResult.OK;
        }
        // Map DistributionResponse failure modes to JobResult outcomes
        // See the replication skill for the full mapping
        return JobResult.FAILED;

    } catch (LoginException | DistributionException e) {
        LOG.error("Distribution composition failed for {}", path, e);
        return JobResult.FAILED;
    }
}

See the replication skill for the full DistributionResponse → JobResult mapping (CANCEL for unrecoverable permission/agent errors, FAILED for transient queue/transport, defensive preview handling).

Review Checklist

Cross-cutting:

• Source topic is a non-resource OSGi topic (replication / workflow / custom) — not org/apache/sling/api/resource/Resource/*
• No javax.jcr.observation.* imports remain
• Business logic lives in a JobConsumer — never inline in handleEvent()
• getServiceResourceResolver(SUBSERVICE) used in try-with-resources
• OSGi DS R6 annotations — no org.apache.felix.scr.annotations.* imports
• SLF4J logging — no System.out / System.err / printStackTrace

EventHandler class:

• Implements EventHandler
• @Component(service = EventHandler.class, property = { EVENT_TOPIC... }) — or service = { EventHandler.class, TopologyEventListener.class } for leader-only
• handleEvent() body only extracts data and calls jobManager.addJob(...)
• handleEvent() body wrapped in try/catch
• @Reference JobManager present; business @Reference fields moved to the JobConsumer
• Event filtering preserves the original filter intent (paths, types, property names)
• Topic shared as a static final String between handler and consumer — not duplicated as a literal

Leader election (when applicable):

• Implements TopologyEventListener if the action must execute once per cluster
• isLeader field is volatile and set in handleTopologyEvent() on TOPOLOGY_INIT and TOPOLOGY_CHANGED
• handleEvent() early-returns when !isLeader
• Run-mode-only check (SlingSettingsService.getRunModes().contains("author")) is not used as a substitute for leader election

JobConsumer class:

• Implements JobConsumer
• @Component(service = JobConsumer.class, property = { PROPERTY_TOPICS + "=<topic>" }) with the same topic used by the handler
• Resolver opened via getServiceResourceResolver(SUBSERVICE) in try-with-resources
• resolver.commit() called if the consumer writes to JCR; PersistenceException caught
• Job data read via job.getProperty("key", Type.class) — not the deprecated JobUtil.getProperty
• Returns JobResult.OK / FAILED / CANCEL deliberately — missing required data is CANCEL, transient errors are FAILED

Configuration:

• Service user created via Repoinit in ui.config
• ServiceUserMapperImpl.amended-*.cfg.json maps <bundle>:<subservice> → the service user (principal-name form)
• Bundle symbolic name in the mapping matches the bundle owning the JobConsumer
• mvn clean install succeeds with no SCR-related or deprecated-API warnings

Troubleshooting

Common Pitfalls

Doing business logic inside handleEvent() — blocks the OSGi event-admin thread. Other handlers across the bundle get delayed delivery. Always offload to a JobConsumer.

Subscribing to org/apache/sling/api/resource/Resource/* topics — these are an internal Sling dispatcher detail, deprecated as an application-facing API. Use ResourceChangeListener (the resource-change-listener skill) for resource observation, not OSGi EventHandler.

Using SlingSettingsService.getRunModes().contains("author") as a singleton guard — run mode says "author vs publish", not "this pod vs other pods". In an author cluster the handler still fires on every node. Use TopologyEventListener for true leader election.

Forgetting volatile on the isLeader field — handleTopologyEvent() and handleEvent() run on different threads; without volatile, the handler thread can read a stale value ind

…(truncated)