AEM 6.5 LTS Replication API
This skill provides comprehensive guidance on using the official Adobe Experience Manager 6.5 LTS Replication API for programmatic replication operations. The API enables custom code to activate, deactivate, and manage content distribution workflows.
When to Use This Skill
Use this skill when you need to:
- Programmatically activate/deactivate content from custom code
- Build custom replication workflows in OSGi services or servlets
- Integrate replication with external systems
- Implement custom replication triggers and automation
- Check replication status in application logic
- Create custom content distribution tools
- Bulk replicate content via scripts
- Implement conditional replication logic
Prerequisites
- AEM 6.5 LTS environment with configured replication agents
- Java development environment for AEM
- Maven project with AEM dependencies
- Understanding of OSGi services and Sling ResourceResolver
- Configured replication agents (see
configure-replication-agentskill) - Service user or user session with replication permissions
Official API Documentation
All public replication APIs are documented in the official Adobe AEM 6.5 LTS JavaDoc:
- Package Summary (Complete API Reference): https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/package-summary.html
- Replicator Interface: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/Replicator.html
- AgentManager Interface: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/AgentManager.html
- ReplicationQueue Interface: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/ReplicationQueue.html
- ReplicationListener Interface: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/ReplicationListener.html
- AgentFilter Interface: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/AgentFilter.html
- Agent Interface: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/Agent.html
- ReplicationAction Class: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/ReplicationAction.html
- ReplicationOptions Class: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/ReplicationOptions.html
- ReplicationStatus Interface: https://developer.adobe.com/experience-manager/reference-materials/6-5-lts/javadoc/com/day/cq/replication/ReplicationStatus.html
Core API Components
1. Replicator Interface
The primary service for managing replication operations.
Service Type: OSGi Service
Package: com.day.cq.replication
Interface: com.day.cq.replication.Replicator
2. ReplicationActionType Enum
Defines the type of replication operation:
3. ReplicationOptions Class
Encapsulates optional parameters for replication requests.
4. ReplicationStatus Interface
Provides status information about replicated content.
Maven Dependencies
The Replication API is provided by the AEM uber-jar. Add to your pom.xml:
The uber-jar version should match your AEM 6.5 LTS installation. The Replication API (com.day.cq.replication.*) is included in the uber-jar and available at runtime.
Replicator Interface Methods
Method 1: replicate(Session, ReplicationActionType, String)
Signature:
Parameters:
session- JCR session (user permissions determine access)type- ReplicationActionType (ACTIVATE, DEACTIVATE, DELETE, etc.)path- Content path to replicate (e.g., "/content/mysite/en/page")
Throws: ReplicationException if replication fails
Description: Triggers replication for a single path with default options.
Example:
Method 2: replicate(Session, ReplicationActionType, String, ReplicationOptions)
Signature:
Parameters:
session- JCR sessiontype- ReplicationActionTypepath- Content pathoptions- ReplicationOptions for custom configuration
Description: Initiates replication with customizable options for one path.
Example:
Method 3: replicate(Session, ReplicationActionType, String[], ReplicationOptions)
Signature:
Parameters:
session- JCR sessiontype- ReplicationActionTypepaths- Array of content paths (String[])options- ReplicationOptions
Description: Handles replication across multiple paths with supplied settings.
Example:
Method 4: checkPermission(Session, ReplicationActionType, String)
Signature:
Parameters:
session- JCR sessiontype- ReplicationActionTypepath- Content path
Throws: ReplicationException if user lacks permissions
Description: Verifies whether a user has sufficient permissions for replication activities.
Example:
Method 5: getReplicationStatus(Session, String)
Signature:
Parameters:
session- JCR sessionpath- Content path
Returns: ReplicationStatus object or null if unavailable
Description: Retrieves the replication status for a given path.
Example:
Method 6: getActivatedPaths(Session, String)
Signature:
Parameters:
session- JCR sessionpath- Root path for subtree
Returns: Iterator of activated paths
Throws: ReplicationException
Description: Returns paths of all activated nodes for the given subtree path.
Example:
ReplicationOptions Class
Encapsulates optional configuration parameters for replication requests.
Official Documentation: ReplicationOptions JavaDoc
Key Methods:
setSynchronous(boolean)
Description: Controls whether replication executes synchronously (blocking) or asynchronously (default).
Parameters:
synchronous-truefor synchronous,falsefor asynchronous (default)
Example:
Use cases:
- Synchronous: When you need confirmation before proceeding (e.g., before redirecting user)
- Asynchronous: Better performance for bulk operations
Thread-Blocking Implications:
When setSynchronous(true) is used, the calling thread blocks until replication completes across all target agents. This has important implications:
- UI Performance: In servlets or sling models rendering pages, synchronous replication blocks the HTTP request thread. For large content or slow networks, this can cause noticeable page load delays or request timeouts.
- Thread Pool Exhaustion: High-traffic scenarios with synchronous replication can exhaust the servlet container's request thread pool, causing cascading failures.
- Recommended Pattern: Use asynchronous replication (
false, the default) for user-facing operations. Reserve synchronous mode for background jobs, workflow steps, or cases where immediate confirmation is critical for correctness (e.g., transactional workflows).
Performance Comparison:
- Asynchronous: Request returns immediately after queueing (~10-50ms)
- Synchronous: Request waits for full replication cycle (500ms-5s typical, longer for large assets or network delays)
setFilter(AgentFilter)
Description: Sets the filter for selecting specific agents for replication.
Parameters:
filter-AgentFilterimplementation
Example:
Use cases:
- Target specific publish instance
- Exclude certain agents
- Route content to specific environments
setSuppressVersions(boolean)
Description: Controls whether to create versions during replication.
Parameters:
suppress-trueto skip version creation,falseotherwise
Example:
setSuppressStatusUpdate(boolean)
Description: Controls whether to update replication status.
Parameters:
suppress-trueto skip status update,falseotherwise
Example:
setRevision(String)
Description: Sets the specific revision to replicate.
Parameters:
revision- Revision identifier
Example:
ReplicationStatus Interface
Provides status information about replicated content.
Official Documentation: ReplicationStatus JavaDoc
Key Methods:
Example:
Complete Implementation Examples
Example 1: OSGi Service with Replication
Example 2: Servlet with Replication
Example 3: Workflow Process Step with Replication
Example 4: Bulk Replication with AgentFilter
Additional Public APIs
Beyond the core Replicator interface, AEM 6.5 LTS provides additional public APIs for advanced replication management. These are all documented in the official package summary.
AgentManager Interface
Manages replication agents programmatically.
Official Documentation: AgentManager JavaDoc
Key Method:
Returns a map of all available agents (agent ID → Agent instance).
Example:
ReplicationQueue Interface
Manages replication queue operations programmatically.
Official Documentation: ReplicationQueue JavaDoc
Key Methods:
Example:
ReplicationListener Interface
Listens for replication events in real-time.
Official Documentation: ReplicationListener JavaDoc
Methods:
Example:
AgentFilter Interface
Filters agents for selective replication (detailed earlier).
Official Documentation: AgentFilter JavaDoc
Method:
Static Fields:
AgentFilter.DEFAULT- Filter for non-specific agentsAgentFilter.OUTBOX_AGENT_FILTER- Filter for distribution operations
Advanced Example:
Agent Interface
Represents a replication agent.
Official Documentation: Agent JavaDoc
Key Methods:
Example:
Exception Handling
ReplicationException Hierarchy
Best Practices for Exception Handling:
Error Handling Patterns
Choose the appropriate error handling pattern based on your use case.
Pattern 1: Throw Exceptions (Library Code)
When to use:
- Library/utility methods
- Workflow process steps
- OSGi services called by other components
- When caller needs to handle errors differently
Characteristics:
- Propagates errors to caller
- Caller decides error handling strategy
- Most flexible for reuse
Example:
Caller handles the exception:
Pattern 2: Return Boolean (Service Layer)
When to use:
- Service layer with internal error logging
- Fire-and-forget operations
- When caller only needs success/failure indicator
- Background/scheduled jobs
Characteristics:
- Logs errors internally
- Returns simple success/failure flag
- Caller doesn't need exception details
Example:
Caller usage:
Pattern 3: HTTP Status Codes (Servlets and REST APIs)
When to use:
- Sling servlets
- REST API endpoints
- Web service integrations
- HTTP-based interfaces
Characteristics:
- Communicates errors via HTTP status codes
- Returns error details in response body
- Standard web semantics
Example:
Pattern Comparison
Choosing the Right Pattern
Use Throw Exception when:
- Building reusable library code
- Caller needs detailed error information
- Different callers need different error handling
- Workflow process steps (WorkflowProcess interface)
Use Return Boolean when:
- Errors are logged and monitored centrally
- Caller only needs success/failure indicator
- Fire-and-forget operations
- Scheduled/background jobs
Use HTTP Status when:
- Building HTTP endpoints (servlets, REST)
- Web service integrations
- Following REST API conventions
- Client needs machine-readable error codes
Anti-Patterns to Avoid
Don't mix patterns:
Don't swallow exceptions silently:
Don't use generic exceptions:
Do be specific:
Security Considerations
1. Use Service Users
Never use admin sessions. Create dedicated service users:
Service User Mapping OSGi Configuration:
Create file: ui.config/src/main/content/jcr_root/apps/myapp/osgiconfig/config.author/org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended-replication.cfg.json
Service User Permissions:
The service user replication-service requires:
- Read permissions on
/content,/conf - Replicate permissions on paths to be activated
- Write permissions on
/var/replication/outbox(for reverse replication)
2. Permission Checks
Always verify permissions before replication:
3. Input Validation
Validate paths and parameters:
ResourceResolver Lifecycle Management
Caller Responsibility Pattern
Important: When accepting ResourceResolver as a method parameter, the caller is responsible for closing it, not the method.
Caller usage:
Try-with-Resources Pattern (Recommended)
When creating the ResourceResolver within your method, use try-with-resources for automatic cleanup:
Resource Leak Prevention
Common mistake - Resource leak:
Correct pattern:
Manual Close Pattern (Legacy)
If try-with-resources is not an option (pre-Java 7 code):
Best Practices
- Prefer try-with-resources for all new code
- Document ownership with JavaDoc when accepting ResourceResolver as parameter
- Always check isLive() before closing in finally blocks
- Never close a ResourceResolver you didn't create
- Use service users - never create admin ResourceResolvers
Performance Optimization
1. Use Asynchronous Replication for Bulk Operations
2. Batch Multiple Paths
Use array variants instead of looping:
3. Suppress Unnecessary Operations
Testing and Validation
Unit Testing with Mocks
Troubleshooting
Common Issues:
Issue: ReplicationException - Agent not found
Issue: Permission denied
Issue: Synchronous replication times out
Issue: Content not appearing on Publish
Related Skills
configure-replication-agent: Set up replication agentsreplicate-content: UI-based content activation methodstroubleshoot-replication: Diagnose and fix replication issues
Success Criteria
- ✓ Successfully integrated Replicator service via OSGi reference
- ✓ Programmatic activation/deactivation working
- ✓ ReplicationOptions configured correctly
- ✓ Permission checks implemented
- ✓ Exception handling in place
- ✓ Service user configured with proper permissions
- ✓ Unit tests passing with mocked Replicator
- ✓ Replication status can be queried
- ✓ Content appears on Publish after API call
- ✓ Logs show successful replication entries
Additional Resources
- Replication API JavaDoc (Complete Package Summary)
- Replicator Interface JavaDoc
- ReplicationOptions JavaDoc
- Official AEM 6.5 LTS Replication Documentation
- AEM 6.5 LTS Replication Troubleshooting Guide
- AEM 6.5 LTS Documentation Hub
- AEM Developer Documentation for OSGi services
- ACS AEM Commons Replication Examples: GitHub


