Understand Java API Best Practices

Adobe Experience Manager (AEM) is built on a rich open-source software stack that exposes many Java APIs for use during development. This article explores the major APIs and when and why they should be used.

AEM is built on 4 primary Java API sets.

• Adobe Experience Manager (AEM)

  • Product abstractions such as pages, assets, workflows, etc.

• Apache Sling Web Framework

  • REST and resource-based abstractions such as resources, value maps, and HTTP requests.

• JCR (Apache Jackrabbit Oak)

  • Data and content abstractions such as node, properties and sessions.

• OSGi (Apache Felix)

  • OSGi application container abstractions such as services and (OSGi) components.

Java API preference “rule of thumb”

The general rule is to prefer the APIs/abstractions the following order:

1. AEM
2. Sling
3. JCR
4. OSGi

If an API is provided by AEM, prefer it over Sling, JCR, and OSGi. If AEM doesn’t provide an API, then prefer Sling over JCR and OSGi.

This order is a general rule, meaning exceptions exist. Acceptable reasons to break from this rule are:

• Well-known exceptions, as described below.

• Required functionality is not available in a higher level API.

• Operating in the context of existing code (custom or AEM product code) which itself uses a less-preferred API, and the cost to move to the new API is unjustifiable.

  • It is better to consistently use the lower level API than create a mix.

AEM APIs

• AEM API JavaDocs

AEM APIs provide abstractions and functionality specific to productized use cases.

For example, AEM’s PageManager and Page APIs provide abstractions for cq:Page nodes in AEM that represent web pages.

While these nodes are available via Sling APIs as Resources, and JCR APIs as Nodes, AEM’s APIs provide abstractions for common use cases. Using the AEM APIs ensures consistent behavior between AEM the product, and customizations and extensions to AEM.

com.adobe.* vs com.day.* APIs

AEM APIs have an intra-package preference, identified by the following Java packages, in order of preference:

1. com.adobe.cq
2. com.adobe.granite
3. com.day.cq

com.adobe.cq supports product use cases whereas com.adobe.granite supports cross-product platform use-cases, such as workflow or tasks (which are used across products: AEM Assets, Sites, etc.).

com.day.cq contains “original” APIs. These APIs address core abstractions and functionalities that existed before and/or around Adobe’s acquisition of [!DNL Day CQ]. These APIs are supported and should not be avoided, unless com.adobe.cq or com.adobe.granite provide a (newer) alternative.

New abstractions such as Content Fragments and Experience Fragments are built out in the com.adobe.cq space rather than com.day.cq described below.

Query APIs

AEM supports multiple query languages. The 3 main languages are JCR-SQL2, XPath and AEM Query Builder.

The most important concern is maintaining a consistent query language across the code base, to reduce complexity and cost to understand.

All the query languages have effectively the same performance profiles, as Apache Oak trans-piles them to JCR-SQL2 for final query execution, and the conversion time to JCR-SQL2 is negligible compared to the query time itself.

The preferred API is AEM Query Builder, which is the highest level abstraction and provides a robust API for constructing, executing and retrieving results for queries, and provides the following:

• Simple, parameterized query construction (query params modeled as a Map)

• Native Java API and HTTP APIs

• OOTB Query Debugger

• OOTB predicates supporting common query requirements

• Extensible API, allowing for the development of custom query predicates

• JCR-SQL2 and XPath can be executed directly via Sling and JCR APIs, returning results a Sling Resources or JCR Nodes, respectively.

Sling APIs

• Apache Sling API JavaDocs

Apache Sling is the RESTful web framework that underpins AEM. Sling provides HTTP request routing, models JCR nodes as resources, provides security context, and much more.

Sling APIs have the added benefit of being built for extension, which means it is often easier and safer to augment behavior of applications built using Sling APIs than the less extensible JCR APIs.

Common uses of Sling APIs

• Accessing JCR nodes as Sling Resources and accessing their data via ValueMaps.

• Providing security context via the ResourceResolver.

• Creating and removing resources via ResourceResolver’s create/move/copy/delete methods.

• Updating properties via the ModifiableValueMap.

• Building request processing building blocks

  • Servlets
  • Servlet Filters

• Asynchronous work processing building blocks

  • Event and Job Handlers
  • Scheduler
  • Sling Models

• Service users

JCR APIs

• JCR 2.0 JavaDocs

The JCR (Java Content Repository) 2.0 APIs is part of a specification for JCR implementations (in the case of AEM, Apache Jackrabbit Oak). All JCR implementation must conform to and implement these APIs, and thus, is the lowest level API for interacting with AEM’s content.

The JCR itself is a hierarchical/tree-based NoSQL datastore AEM uses as its content repository. The JCR has a vast array of supported APIs, ranging from content CRUD to querying content. Despite this robust API, it is rare they’re preferred over the higher level AEM and Sling abstractions.

Always prefer the JCR APIs over the Apache Jackrabbit Oak APIs. The JCR API’s are for interacting with a JCR repository, whereas the Oak APIs are for implementing a JCR repository.

Common misconceptions about JCR APIs

While the JCR is AEM’s content repository, its APIs are NOT the preferred method for interacting with the content. Instead prefer the AEM APIs (Page, Assets, Tag, etc.) or Sling Resource APIs as they provide better abstractions.

Common uses of JCR APIs

• Access control management

• Authorizable management (users/groups)

• JCR observation (listening for JCR events)

• Creating deep node structures

  • While the Sling APIs support the creation of resources, the JCR APIs have convenience methods in JcrUtils and JcrUtil that expedite creating deep structures.

OSGi APIs

• OSGi R6 JavaDocs
• OSGi Declarative Services 1.2 Component Annotations JavaDocs
• OSGi Declarative Services 1.2 Metatype Annotations JavaDocs
• OSGi Framework JavaDocs

There is little overlap between the OSGi APIs and the higher level APIs (AEM, Sling, and JCR), and the need to use OSGi APIs is rare and requires a high-level of AEM development expertise.

OSGi vs Apache Felix APIs

OSGi defines a specification all OSGi containers must implement and conform to. AEM’s OSGi implementation, Apache Felix, provides several of its own APIs as well.

• Prefer OSGi APIs (org.osgi) over Apache Felix APIs (org.apache.felix).

Common uses of OSGi APIs

• OSGi annotations for declaring OSGi services and components.

  • Prefer OSGi Declarative Services (DS) 1.2 Annotations over Felix SCR Annotations for declaring OSGi services and components

• OSGi APIs for dynamically in-code un/registering OSGi services/components.

  • Prefer the use of OSGi DS 1.2 annotations when conditional OSGi Service/Component management is not needed (which is most often the case).

Exceptions to the rule

The following are common exceptions to the rules defined above.

AEM Asset APIs

• Prefer com.day.cq.dam.api over com.adobe.granite.asset.api.

  • While the com.day.cq Assets API’s provide more complimentary tooling to AEM’s asset management use-cases.
  • The Granite Assets APIs support low-level asset management use-cases (version, relations).

Query APIs

• AEM QueryBuilder does not support certain query functions such as suggestions, spellcheck and index hints amongst other less common functions. To query with these functions JCR-SQL2 is preferred.

Sling Servlet Registration

• Sling servlet registration, prefer OSGi DS 1.2 annotations w/ @SlingServletResourceTypes over @SlingServlet

Sling Filter Registration

• Sling filter registration, prefer OSGi DS 1.2 annotations w/ @SlingServletFilter over @SlingFilter

Helpful code snippets

The following are helpful Java code snippets that illustrate best practices for common use cases using discussed APIs. These snippets also illustrate how to move from less preferred APIs to more preferred APIs.

JCR Session to Sling ResourceResolver

Auto-closing Sling ResourceResolver

Since AEM 6.2, the Sling ResourceResolver is AutoClosable in a try-with-resources statement. Using this syntax, an explicit call to resourceResolver .close() is not needed.

@Reference
ResourceResolverFactory rrf;
...
Map<String, Object> authInfo = new HashMap<String, Object>();
authInfo.put(JcrResourceConstants.AUTHENTICATION_INFO_SESSION, jcrSession);

try (ResourceResolver resourceResolver = rrf.getResourceResolver(authInfo)) {
    // Do work with the resourceResolver
} catch (LoginException e) { .. }

Manually closed Sling ResourceResolver

ResourceResolvers can be must be manually closed in a finally block, if the auto-closing technique shown above cannot be used.

@Reference
ResourceResolverFactory rrf;
...
Map<String, Object> authInfo = new HashMap<String, Object>();
authInfo.put(JcrResourceConstants.AUTHENTICATION_INFO_SESSION, jcrSession);

ResourceResolver resourceResolver = null;

try {
    resourceResolver = rrf.getResourceResolver(authInfo);
    // Do work with the resourceResolver
} catch (LoginException e) {
   ...
} finally {
    if (resourceResolver != null) { resourceResolver.close(); }
}

JCR Path to Sling Resource

Resource resource = ResourceResolver.getResource("/path/to/the/resource");

JCR Node to Sling Resource

Resource resource = resourceResolver.getResource(node.getPath());

Sling Resource to AEM Asset

Recommended approach

DamUtil.resolveToAsset(..)resolves any resource under the dam:Asset to the Asset object by walking up the tree as needed.

Asset asset = DamUtil.resolveToAsset(resource);

Alternative approach

Adapting a resource to an Asset requires the resource itself to be the dam:Asset node.

Asset asset = resource.adaptTo(Asset.class);

Sling Resource to AEM Page

Recommended approach

pageManager.getContainingPage(..) resolves any resource under the cq:Page to the Page object by walking up the tree as needed.

PageManager pageManager = resourceResolver.adaptTo(PageManager.class);
Page page = pageManager.getContainingPage(resource);
Page page2 = pageManager.getContainingPage("/content/path/to/page/jcr:content/or/component");

Alternative approach

Adapting a resource to a Page requires the resource itself to be the cq:Page node.

Page page = resource.adaptTo(Page.class);

Read AEM Page properties

Use the Page object’s getters to get well known properties (getTitle(), getDescription(), etc.) and page.getProperties() to obtain the [cq:Page]/jcr:content ValueMap for retrieving other properties.

Page page = resource.adaptTo(Page.class);
String title = page.getTitle();
Calendar value = page.getProperties().get("cq:lastModified", Calendar.getInstance());

Read AEM Asset metadata properties

The Asset API provides convenient methods for reading properties from the [dam:Asset]/jcr:content/metadata node. Note that this is not a ValueMap, the 2nd parameter (default value, and auto-type casting) is not supported.

Asset asset = resource.adaptTo(Asset.class);
String title = asset.getMetadataValue("dc:title");
Calendar lastModified = (Calendar) asset.getMetadata("cq:lastModified");

Read Sling Resource properties

When properties are stored in locations (properties or relative resources) where the AEM APIs (Page, Asset) cannot directly access, the Sling Resources and ValueMaps can be used to obtain the data.

ValueMap properties = resource.getValueMap();
String value = properties.get("jcr:title", "Default title");
String relativeResourceValue = properties.get("relative/propertyName", "Default value");

In this case, the AEM object may have to be converted into a Sling Resource to efficiently locate the desired property or sub-resource.

AEM Page to Sling Resource

Resource resource = page.adaptTo(Resource.class);

AEM Asset to Sling Resource

Resource resource = asset.adaptTo(Resource.class);

Write properties using Sling’s ModifiableValueMap

Use Sling’s ModifiableValueMap to write properties to nodes. This can only write to the immediate node (relative property paths are not supported).

Note the call to .adaptTo(ModifiableValueMap.class) requires write permissions to the resource, else it will return null.

ModifiableValueMap properties = resource.adaptTo(ModifiableValueMap.class);

properties.put("newPropertyName", "new value");
properties.put("propertyNameToUpdate", "updated value");
properties.remove("propertyToRemove");

resource.getResourceResolver().commit();

Create an AEM Page

Always use PageManager to create pages as it takes a Page Template, is required to properly define and initialize Pages in AEM.

String templatePath = "/conf/my-app/settings/wcm/templates/content-page";
boolean autoSave = true;

PageManager pageManager = resourceResolver.adaptTo(PageManager.class);
pageManager.create("/content/parent/path", "my-new-page", templatePath, "My New Page Title", autoSave);

if (!autoSave) { resourceResolver.commit(); }

Create a Sling Resource

ResourceResolver supports basic operations for creating resources. When creating higher level abstractions (AEM Pages, Assets, Tags, etc.) use the methods provided by their respective Managers.

resourceResolver.create(parentResource, "my-node-name", new ImmutableMap.Builder<String, Object>()
           .put("jcr:primaryType", "nt:unstructured")
           .put("jcr:title", "Hello world")
           .put("propertyName", "Other initial properties")
           .build());

resourceResolver.commit();

Delete a Sling Resource

ResourceResolver supports removing a resource. When creating higher-level abstractions (AEM Pages, Assets, Tags, etc.) use the methods provided by their respective Managers.

resourceResolver.delete(resource);

resourceResolver.commit();