Remove Deprecated API — AEM as a Cloud Service

This pattern is executed by the code-assessment runbook — follow ../references/runbook.md for the outer flow (preflight → plan → apply → verify, run log). This skill supplies the plugin-driven detection and the hint-driven fix recipe the runbook applies.

Overview

Adobe curates the list of deprecated / removed AEM APIs inside the AEM SDK's api-regions metadata; Cloud Manager's region-deprecated-api analyser task consumes that JSON at build time. The AEM Analyser Maven Plugin (com.adobe.aem:aemanalyser-maven-plugin) runs the same task locally against the project's built bundles. This skill uses the plugin as its detection engine — no curated tables, no static lists, no drift.

For each deprecated package the plugin reports, its log line contains a hint: the deprecated.msg field from the SDK metadata, which typically names a successor package (e.g. "Please use org.apache.sling.xss instead"). Fixes are derived from that hint at plan time. When the hint names no successor, the recipe consults the Adobe Experience League API-removal guidance as a documented fallback.

Classification — confirm this pattern applies

• Any *.java, pom.xml, or OSGi config file the AEM Analyser Maven Plugin reports under region-deprecated-api (i.e. any Usage of deprecated ... found log line produced by mvn verify against the project).
• Cloud Manager code-quality pipeline failures citing region-deprecated-api, api-regions-check, Import-Package not satisfied, or bundle-unversioned-packages violations.

The plugin only reports past-due deprecations by default (entries whose for-removal date has already elapsed). Future-dated deprecations are not touched; re-running the skill after each removal date passes picks them up automatically — the list is live.

Discovery — two-phase

The detector lives in the shared Java analyzer (scripts/analyzer/detectors/RemoveDeprecatedApi.java), same shape as every other pattern's detector — but its rules are loaded at run time from a preflight-produced cache, not hardcoded.

Phase 1 — preflight (populates the rules cache)

bash plugins/aem/cloud-service/skills/code-assessment/remove-deprecated-api/scripts/detect.sh <project-root>

detect.sh:

1. Resolves the latest com.adobe.aem:aemanalyser-maven-plugin and the latest com.adobe.aem:aem-sdk-api releases from Maven Central (maven-metadata.xml); each can be pinned with --pin-plugin <version> / --pin-sdk <version>. The freshest SDK is used by default because Cloud Manager itself runs the analyser against the latest SDK — matching that behaviour surfaces every deprecation the pipeline will flag. If the project's pom.xml pins an older SDK via <sdkVersion>X.Y.Z</sdkVersion> or <useDependencyVersions>true</useDependencyVersions> inside the analyser plugin config, detect.sh overrides at the CLI (-DsdkVersion=<latest> and -DsdkUseDependency=false) so the fresh set is used just for the preflight — no pom edit. Pass --respect-pom-sdk to honour the pom's pin instead.
2. Invokes the analyser by its fully-qualified com.adobe.aem:aemanalyser-maven-plugin:<version>:project-analyse coordinates, so the resolved version runs whether or not the project declares the plugin — the pom is never modified (no patch, no backup, no restore). Command shape: mvn package com.adobe.aem:aemanalyser-maven-plugin:<version>:project-analyse … — the package phase (override with --goal) builds the module artifacts that project-analyse inspects. Log path: /tmp/aem-analyser.log (override with --log <path>).
3. Parses Usage of deprecated package found : <pkg> : <hint> Deprecated since <since> For removal : <date> and Usage of deprecated library found : <lib>, package(s) : <start>...<end> : <hint> lines.
4. Writes the rules cache TSV — <package>\t<hint>\t<for_removal> per line — at $AEM_DEPRECATED_API_RULES (env override) or $TMPDIR/aem-code-assessment/deprecated-api-rules.tsv (default).
5. Emits a JSON summary on stdout (findings + meta) for callers that don't chain through analyze.sh.

Phase 2 — analyzer (consumes the cache, emits findings)

bash plugins/aem/cloud-service/skills/code-assessment/scripts/analyze.sh <workspace-root>

The Java RemoveDeprecatedApi detector reads the rules TSV, matches each rule's package against every import in the corpus (longest-prefix match), applies today's past-due gating as a defence-in-depth, and emits findings in the standard {pattern,file,line,snippet} shape with an added hint field carrying the analyser message.

Findings shape — the standard runbook shape plus an optional hint:

{
  "findings": [
    {
      "pattern": "remove-deprecated-api",
      "file": "core/src/main/java/com/example/MyService.java",
      "line": 5,
      "snippet": "org.apache.log4j.Logger",
      "hint": "The log4j 1.x libraries are deprecated. Please use org.slf4j instead."
    }
  ],
  "warnings": []
}

If the cache is missing — detect.sh was not run, or was run offline and failed — the detector emits a single warning:

deprecated-api-rules-missing: expected TSV at <path> — run remove-deprecated-api/scripts/detect.sh preflight first

and produces no findings for this pattern. Other detectors continue unaffected.

Scope: workspace roots only. Exclude code-assessment/ skill files.

Resolution contract

hint-driven — every fix derives from the analyser's hint field for that finding. The recipe (recipe.md Step 3) parses the hint for a successor-package phrase ("Please use X instead", "Use X instead", "X should be used") and applies the edit. When the hint names no successor, the recipe falls back to Adobe Experience League's API-removal guidance page via WebFetch.

Verification — before applying, the successor must be resolvable on the project's classpath. If it is not, either add the required Maven dependency (with user consent) or record the finding as manual-action-required.

Manual-only items (cannot be auto-fixed; document in report, do not attempt edits):

• Deep integration cases where hint says "not supported in AEM as a Cloud Service" with no successor named on Experience League (e.g. org.apache.felix.webconsole, parts of com.drew).
• Guava usage beyond simple Lists.newArrayList() / ImmutableList.of() — caching, event bus, complex data structures — where replacement requires design decisions.
• Reflection or dynamic loading against the deprecated type — the scanner cannot see it and the fix is not mechanical.

Review checklist

• Latest aemanalyser-maven-plugin resolved from Maven Central
• Initial build passed before any transformations (mvn compile)
• Analyser log parsed; findings carry a non-empty hint where the SDK provides one
• Each finding's successor package (from hint or Experience League) verified on the classpath before applying
• Step 3 edits applied surgically (imports rewritten, deps updated, OSGi configs deleted where the plugin reports them as unmodifiable)
• Post-edit build checked; residual compilation errors routed to AI-fix phase
• Each AI-assisted fix marked with // Fixed by AEM Modernizer AI above the change
• Final build passes and the analyser — re-invoked via the fully-qualified project-analyse goal — now reports zero past-due deprecations
• Manual-action items documented in the report

Troubleshooting fingerprints

Recipe pointer

Read recipe.md fully before applying. The recipe covers the plugin setup + preflight scan, the hint parsing rules, the Experience League fallback flow, the AI-fix loop for compilation errors introduced by rewrites, and the report format.