/sling-distribution

name: sling-distribution
license: Apache-2.0
description: |
  Monitor and react to content distribution events using Sling Distribution API (org.apache.sling.distribution).
  Covers distribution event handling, queue monitoring, and distribution lifecycle tracking.

AEM Cloud Service Sling Distribution Event Handling

Monitor and react to content distribution lifecycle events using the Sling Distribution API.

When to Use This Skill

Use Sling Distribution event handling for:

• **Monitoring distribution lifecycle**: Track package creation, queueing, and delivery
• **Custom post-distribution actions**: Cache warming, notifications, analytics
• **Distribution auditing**: Log and track all distribution events
• **Failure handling**: React to dropped packages and distribution failures
• **Integration workflows**: Trigger external systems after successful distribution

**For programmatic publishing**, use the [Replication API](../replication/SKILL.md) instead.

Official API Documentation

**Javadoc**: https://developer.adobe.com/experience-manager/reference-materials/cloud-service/javadoc/org/apache/sling/distribution/package-summary.html

**Key Packages**:

• `org.apache.sling.distribution` - Core distribution interfaces
• `org.apache.sling.distribution.event` - Event topics and properties
• `org.apache.sling.distribution.queue` - Queue monitoring

Understanding Sling Distribution in Cloud Service

What is Sling Distribution?

Sling Distribution is the **underlying transport mechanism** for content replication in AEM Cloud Service. When you use the Replication API (`Replicator.replicate()`), Sling Distribution handles:

1. **Package Creation**: Content is assembled into distribution packages 2. **Queueing**: Packages are queued for delivery 3. **Transport**: Packages are sent to Adobe Developer pipeline service 4. **Import**: Target tier imports and applies the content

Architecture Flow

Replication API Call
       ↓
[AGENT_PACKAGE_CREATED] - Package assembled
       ↓
[AGENT_PACKAGE_QUEUED] - Package added to queue
       ↓
[AGENT_PACKAGE_DISTRIBUTED] - Package sent to pipeline
       ↓
[IMPORTER_PACKAGE_IMPORTED] - Package imported on target tier

**OR**

[AGENT_PACKAGE_DROPPED] - Package failed and was removed

Distribution Event Topics

Available Event Topics

Sling Distribution fires events at each stage of the distribution lifecycle:

| Event Topic | When It Fires | Use Case | |-------------|---------------|----------| | `AGENT_PACKAGE_CREATED` | After package creation | Track what's being published | | `AGENT_PACKAGE_QUEUED` | After package is queued | Monitor queue depth | | `AGENT_PACKAGE_DISTRIBUTED` | After successful distribution | Trigger post-publish actions | | `AGENT_PACKAGE_DROPPED` | When package fails and is dropped | Handle failures, alert on-call | | `IMPORTER_PACKAGE_IMPORTED` | After successful import on target | Confirm content is live |

Event Topic Constants

import org.apache.sling.distribution.event.DistributionEventTopics;

// Event topic strings
DistributionEventTopics.AGENT_PACKAGE_CREATED      // Package created
DistributionEventTopics.AGENT_PACKAGE_QUEUED       // Package queued
DistributionEventTopics.AGENT_PACKAGE_DISTRIBUTED  // Package distributed
DistributionEventTopics.AGENT_PACKAGE_DROPPED      // Package dropped
DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED  // Package imported

Listening to Distribution Events

Example: Basic Distribution Event Logger

import org.apache.sling.distribution.event.DistributionEventTopics;
import org.apache.sling.distribution.event.DistributionEventProperties;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventHandler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Component(
    service = EventHandler.class,
    property = {
        org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" + 
            DistributionEventTopics.AGENT_PACKAGE_CREATED,
        org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" + 
            DistributionEventTopics.AGENT_PACKAGE_QUEUED,
        org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" + 
            DistributionEventTopics.AGENT_PACKAGE_DISTRIBUTED,
        org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" + 
            DistributionEventTopics.AGENT_PACKAGE_DROPPED,
        org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" + 
            DistributionEventTopics.IMPORTER_PACKAGE_IMPORTED
    }
)
public class DistributionEventLogger implements EventHandler {
    
    private static final Logger LOG = LoggerFactory.getLogger(DistributionEventLogger.class);
    
    @Override
    public void handleEvent(Event event) {
        String topic = event.getTopic();
        
        // Extract event properties
        String componentName = (String) event.getProperty(
            DistributionEventProperties.DISTRIBUTION_COMPONENT_NAME
        );
        String componentKind = (String) event.getProperty(
            DistributionEventProperties.DISTRIBUTION_COMPONENT_KIND
        );
        String distributionType = (String) event.getProperty(
            DistributionEventProperties.DISTRIBUTION_TYPE
        );
        String packageId = (String) event.getProperty(
            DistributionEventProperties.DISTRIBUTION_PACKAGE_ID
        );
        String[] paths = (String[]) event.getProperty(
            DistributionEventProperties.DISTRIBUTION_PATHS
        );
        Long timestamp = (Long) event.getProperty(
            DistributionEventProperties.DISTRIBUTION_ENQUEUE_TIMESTAMP
        );
        
        LOG.info("Distribution Event: topic={}, component={}, type={}, packageId={}, paths={}, timestamp={}",
            topic, componentName, distributionType, packageId, 
            paths != null ? String.join(",", paths) : "null",
            timestamp
        );
    }
}

Event Properties

##