adobe/best-practices

AEM as a Cloud Service — Best Practices

Platform guidance for AEM as a Cloud Service: Java/OSGi (what to use, what to avoid, how to refactor legacy patterns) and HTL (component .html templates, Cloud SDK HTL lint).

This skill holds the pattern transformation modules (references/*.md). They ship with the aem-cloud-service plugin; use this skill without the migration skill for greenfield or maintenance work that only needs these references. Use migration when you need BPA/CAM orchestration on top.

Quick pick: Open the Pattern Reference Modules table below → jump to the matching references/<file>.md → read it fully before editing. For Java: Felix SCR, resolvers, or logging, use Java / OSGi baseline links first when those appear in the same change set.

When to Use This Skill

Use this skill when you need to:

• Apply AEM as a Cloud Service constraints to Java/OSGi code (new or existing)
• Refactor legacy Java patterns into supported APIs (same modules migration uses)
• Follow consistent rules across schedulers, replication, JCR observation listeners (eventListener), OSGi event handlers (eventHandler), and DAM assets
• Fix HTL (Sightly) issues from the AEM Cloud SDK build, especially data-sly-test: redundant constant value comparison
• Read step-by-step transformation and validation checklists for a specific pattern

For BPA/CAM orchestration (collections, CSV, MCP project selection), use the migration skill (skills/aem/cloud-service/skills/migration/).

Pattern Reference Modules

Each supported pattern has a dedicated module under references/ relative to this SKILL.md.

| Pattern / topic | BPA Pattern ID | Module file | Status | |-----------------|----------------|-------------|--------| | Scheduler | scheduler | references/scheduler.md | Ready | | Resource Change Listener | resourceChangeListener | references/resource-change-listener.md | Ready | | Replication | replication | references/replication.md | Ready | | Event listener (JCR observation) | eventListener | references/event-migration.md | Ready | | Event handler (OSGi Event Admin) | eventHandler | references/event-migration.md | Ready | | Asset Manager | assetApi | references/asset-manager.md | Ready | | Felix SCR → OSGi DS | — | references/scr-to-osgi-ds.md | Ready | | ResourceResolver + SLF4J | — | references/resource-resolver-logging.md | Ready | | HTL: data-sly-test redundant constant | — (HTL lint) | references/data-sly-test-redundant-constant.md | Ready | | (Prerequisites hub) | — | references/aem-cloud-service-pattern-prerequisites.md | — |

Event listener vs event handler (not the same): eventListener is JCR observation — the JCR API for repository change callbacks (javax.jcr.observation.EventListener, onEvent). eventHandler is OSGi Event Admin — whiteboard-style OSGi events (org.osgi.service.event.EventHandler, handleEvent). Both migrate via references/event-migration.md (Path A vs Path B). resourceChangeListener is separate: Sling ResourceChangeListener, module references/resource-change-listener.md.

Before changing code for a pattern: read the module for that pattern in full. Modules include classification criteria, ordered transformation steps, and validation checklists.

Java / OSGi baseline (same skill; no separate installables)

SCR→DS and ResourceResolver/logging are reference modules under references/ — not separate skills. Read them when relevant instead of re-embedding the same steps inside each pattern file.

• Hub: references/aem-cloud-service-pattern-prerequisites.md
• Modules: references/scr-to-osgi-ds.md, references/resource-resolver-logging.md

Critical Rules (All Patterns)

These rules apply to every pattern module. Violation means incorrect migration or unsafe Cloud Service code.

• READ THE PATTERN MODULE FIRST — never transform code without reading the module
• READ scr-to-osgi-ds.md and resource-resolver-logging.md when SCR, ResourceResolver, or logging are in scope (pattern modules link via the prerequisites hub; do not duplicate long guides inline)
• DO preserve environment-specific guards (e.g. isAuthor() run mode checks)
• DO NOT change business logic inside methods (Java) or logical show/hide intent (HTL) unless the module explicitly allows it
• DO NOT rename classes unless the pattern module explicitly says to
• DO NOT invent values — extract from existing code
• DO NOT edit files outside the scope agreed with the user (e.g. only BPA targets or paths they named)
• DO keep searches, discovery, and edits for the customer's AEM sources inside the IDE workspace root(s) currently open; DO NOT grep or walk directories outside that boundary to find Java unless the user explicitly points there

Manual Pattern Hints (Classification)

When no BPA list exists, scan imports and types to pick a module:

| Look for | Pattern | |----------|---------| | org.apache.sling.commons.scheduler.Scheduler or scheduler.schedule( with Runnable | scheduler | | implements ResourceChangeListener | resourceChangeListener | | com.day.cq.replication.Replicator or org.apache.sling.replication.* | replication | | JCR observation: javax.jcr.observation.EventListener, onEvent(EventIterator), javax.jcr.observation.* | eventListener | | OSGi Event Admin: org.osgi.service.event.EventHandler, substantive handleEvent (resolver/session/node work) | eventHandler | | com.day.cq.dam.api.AssetManager create/remove asset APIs | assetApi | | org.apache.felix.scr.annotations | read references/scr-to-osgi-ds.md (often combined with a BPA pattern) | | getAdministrativeResourceResolver, System.out / printStackTrace | read references/resource-resolver-logging.md | | HTL: build warning data-sly-test: redundant constant value comparison, or .html under ui.apps / jcr_root with bad data-sly-test | read references/data-sly-test-redundant-constant.md |

If multiple patterns match, ask which to fix first.

Relationship to Migration

The migration skill defines one-pattern-per-session workflow, BPA/CAM/MCP flows, and user messaging. It delegates all detailed transformation steps to this skill's references/ modules. It uses a {best-practices} repo-root path alias to this folder (see its SKILL.md). Keep platform truth here; keep orchestration there.