sling-distribution

What this skill does

# 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

```java
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

```java
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

### Available Event Properties

Every distribution event contains these properties:

| Property | Type | Description |
|----------|------|-------------|
| `DISTRIBUTION_COMPONENT_NAME` | String | Name of component generating the event |
| `DISTRIBUTION_COMPONENT_KIND` | String | Kind of component (agent, importer, etc.) |
| `DISTRIBUTION_TYPE` | String | Type of distribution request (ADD, DELETE, etc.) |
| `DISTRIBUTION_PACKAGE_ID` | String | Unique package identifier |
| `DISTRIBUTION_PATHS` | String[] | Content paths being distributed |
| `DISTRIBUTION_DEEP_PATHS` | String[] | Deep paths (full subtree) |
| `DISTRIBUTION_ENQUEUE_TIMESTAMP` | Long | When item was enqueued (milliseconds) |

### Accessing Event Properties

```java
import org.apache.sling.distribution.event.DistributionEventProperties;

@Override
public void handleEvent(Event event) {
    // Component information
    String componentName = (String) event.getProperty(
        DistributionEventProperties.DISTRIBUTION_COMPONENT_NAME
    );
    String componentKind = (String) event.getProperty(
        DistributionEventProperties.DISTRIBUTION_COMPONENT_KIND
    );
    
    // Distribution details
    String type = (String) event.getProperty(
        DistributionEventProperties.DISTRIBUTION_TYPE
    );
    String packageId = (String) event.getProperty(
        DistributionEventProperties.DISTRIBUTION_PACKAGE_ID
    );
    
    // Content paths
    String[] paths = (String[]) event.getProperty(
        DistributionEventProperties.DISTRIBUTION_PATHS
    );
    String[] deepPaths = (String[]) event.getProperty(
        DistributionEventProperties.DISTRIBUTION_DEEP_PATHS
    );
    
    // Timing
    Long enqueueTime = (Long) event.getProperty(
        DistributionEventProperties.DISTRIBUTION_ENQUEUE_TIMESTAMP
    );
}
```

## Common Use Cases

### Use Case 1: Alert on Distribution Failures

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

@Component(
    service = EventHandler.class,
    property = {
        org.osgi.service.event.EventConstants.EVENT_TOPIC + "=" + 
            DistributionEventTopics.AGENT_PACKAGE_DROPPED
    }
)
public class DistributionFailureAlertHandler implements EventHandler {
    
    private static final Logger LOG = LoggerFact