Bonnes pratiques relatives aux API Java™

Adobe Experience Manager (AEM) repose sur une riche pile logicielle open source qui expose de nombreuses API Java™ à utiliser pendant le développement. Cet article couvre les principales API et explique quand et pourquoi elles doivent être utilisées.

AEM repose sur quatre ensembles principaux d’API Java™.

Règle de base de préférence d’API Java™

La règle générale est de préférer les API/abstractions dans l’ordre suivant :

Si une API est fournie par AEM, préférez-la à Sling, JCR et OSGi. Si AEM ne fournit pas d’API, préférez Sling à JCR et OSGi.

Cet ordre est une règle générale, ce qui signifie qu’il existe des exceptions. Les raisons possibles de dérogation à cette règle sont les suivantes :

API d’AEM

Les API d’AEM fournissent des abstractions et des fonctionnalités spécifiques aux cas d’utilisation productifs.

Par exemple, les API AEM PageManager et Page fournissent des abstractions pour les nœuds cq:Page dans AEM représentant les pages web.

Alors que ces nœuds sont disponibles via les API Sling en tant que ressources et via les API JCR en tant que nœuds, les API AEM fournissent des abstractions pour les cas d’utilisation courants. L’utilisation des API d’AEM permet d’assurer un comportement cohérent entre AEM, le produit, ainsi que les personnalisations et les extensions d’AEM.

com.adobe.* et com.day.* API

Les API d’AEM ont une préférence intra-package, identifiée par les packages Java™ suivants, par ordre de préférence :

Le package com.adobe.cq prend en charge les cas d’utilisation de produits, alors que com.adobe.granite prend en charge les cas d’utilisation de plateformes inter-produits, tels que les workflows et les tâches (qui sont utilisés dans plusieurs produits : AEM Assets, Sites, etc.).

Le package com.day.cq contient des API « originales ». Ces API traitent des abstractions et fonctionnalités de base qui existaient avant et/ou autour de l’acquisition par Adobe de Day CQ. Ces API sont prises en charge et doivent être évitées, sauf si les packages com.adobe.cq ou com.adobe.granite ne fournissent PAS d’alternative (plus récente).

De nouvelles abstractions telles que Content Fragments et Experience Fragments sont conçues dans l’espace com.adobe.cq plutôt que celui com.day.cq décrit ci-dessous.

API de requête

AEM prend en charge plusieurs langages de requête. Les trois langages principaux sont : JCR-SQL2, XPath et AEM Query Builder.

La préoccupation la plus importante est de conserver un langage de requête cohérent dans l’ensemble de la base de code, afin de réduire la complexité et les coûts de compréhension.

Tous les langages de requête possèdent effectivement les mêmes profils de performance, comme Apache Oak les transpile vers JCR-SQL2 pour l’exécution de la requête finale, et le temps de conversion vers JCR-SQL2 est négligeable par rapport au temps de requête lui-même.

L’API préférée est AEM Query Builder, qui constitue le niveau d’abstraction le plus élevé et fournit une API robuste pour la création, l’exécution et la récupération des résultats des requêtes, et fournit les éléments suivants :

API Sling

Apache Sling est le framework web RESTful qui sous-tend AEM. Sling fournit le routage des requêtes HTTP, modélise les nœuds JCR en tant que ressources, fournit un contexte de sécurité, etc.

Les API Sling ont l’avantage supplémentaire d’être créées pour l’extension, ce qui signifie qu’il est souvent plus facile et plus sûr d’augmenter le comportement des applications créées à l’aide des API Sling plutôt que des API JCR moins extensibles.

Utilisations courantes des API Sling

API JCR

Les API JCR (Java™ Content Repository) 2.0 font partie d’une spécification pour les implémentations JCR (dans le cas d’AEM, Apache Jackrabbit Oak). Toute implémentation JCR doit se conformer à ces API et les mettre en œuvre. Il s’agit donc de l’API de niveau le plus bas pour interagir avec le contenu AEM.

Le JCR lui-même est un magasin de données NoSQL hiérarchique/basé sur une arborescence qu’AEM utilise comme référentiel de contenu. Le JCR dispose d’une vaste gamme d’API prises en charge, allant des opérations CRUD de contenu à l’interrogation de contenu. Malgré la robustesse de ces API, il est rare qu’elles soient privilégiées par rapport aux abstractions Sling et AEM de niveau supérieur.

Privilégiez toujours les API JCR plutôt que les API Apache Jackrabbit Oak. Les API JCR sont destinées à l’interaction avec un référentiel JCR, tandis que les API Oak sont destinées à l’implémentation d’un référentiel JCR.

Erreurs courantes à propos des API JCR

Bien que JCR soit le référentiel de contenu d’AEM, ses API ne constituent PAS la méthode privilégiée pour interagir avec le contenu. Privilégiez plutôt les API AEM (Page, Ressources, Balise, etc.) ou les API de ressource Sling, car elles fournissent de meilleures abstractions.

Utilisations courantes des API JCR

API OSGi

Les API OSGi et les API de niveau supérieur (AEM, Sling, et JCR) se chevauchent peu. Il est rare d’avoir à utiliser les API OSGi et cela nécessite un haut niveau d’expertise en développement AEM.

API OSGi vs Apache Felix

OSGi définit une spécification que tous les conteneurs OSGi doivent implémenter et respecter. L’implémentation OSGi d’AEM, Apache Felix, fournit également plusieurs de ses propres API.

Utilisations courantes des API OSGi

Exceptions à la règle

Vous trouverez ci-dessous des exceptions courantes aux règles définies ci-dessus.

API OSGi

Lorsque vous traitez des abstractions OSGi de bas niveau, telles que la définition ou la lecture dans les propriétés de composant OSGi, les abstractions les plus récentes fournies par org.osgi sont privilégiées par rapport aux abstractions Sling de niveau supérieur. Les abstractions Sling concurrentes n’ont pas été marquées comme @Deprecated et suggèrent l’alternative org.osgi.

Notez également que la définition de nœud de configuration OSGi préfère le format cfg.json au format sling:OsgiConfig.

API Assets AEM

API de requête

Enregistrement de servlet Sling sling-servlet-registration

Enregistrement de filtre Sling sling-filter-registration

Extraits de code utiles

Vous trouverez ci-dessous des extraits de code Java™ qui illustrent les bonnes pratiques relatives aux cas d’utilisation courants des API mentionnées. Ces extraits illustrent également comment passer d’API au niveau de préférence inférieur à des API dont le niveau de préférence est supérieur.

Session JCR à ResourceResolver Sling

Fermer automatiquement ResourceResolver Sling

Depuis AEM 6.2, le ResourceResolver Sling est AutoClosable dans une instruction try-with-resources. Avec cette syntaxe, un appel explicite à resourceResolver .close() n’est pas nécessaire.

@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) { .. }

Fermer manuellement ResourceResolver Sling

ResourceResolver peut être fermé manuellement dans un bloc finally, si la technique de fermeture automatique illustrée ci-dessus ne peut pas être utilisée.

@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(); }
}

Chemin JCR vers Resource Sling

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

Nœud JCR vers Resource Sling

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

Resource Sling vers AEM Assets

Approche recommandée

La fonction DamUtil.resolveToAsset(..) résout n’importe quelle ressource sous dam:Asset vers l’objet Asset en montant l’arborescence selon les besoins.

Asset asset = DamUtil.resolveToAsset(resource);

Approche alternative

L’adaptation d’une ressource à un objet Asset nécessite que la ressource elle-même soit le nœud dam:Asset.

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

Ressource Sling vers la page AEM

Approche recommandée

pageManager.getContainingPage(..) résout toute ressource sous cq:Page vers l’objet Page en montant l’arborescence selon les besoins.

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

Approche alternative alternative-approach-1

L’adaptation d’une ressource à un objet Page requiert que la ressource elle-même soit le nœud cq:Page.

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

Lire les propriétés de page AEM

Utilisez les getters de l’objet Page pour obtenir des propriétés connues (getTitle(), getDescription(), etc.) et page.getProperties() pour obtenir la ValueMap [cq:Page]/jcr:content pour récupérer d’autres propriétés.

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

Lire des propriétés de métadonnées Asset AEM

L’API Asset fournit des méthodes pratiques pour lire les propriétés à partir du nœud [dam:Asset]/jcr:content/metadata. Il ne s’agit pas d’une ValueMap, le deuxième paramètre (valeur par défaut et conversion de type automatique) n’est pas pris en charge.

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

Lire des propriétés Resource Sling read-sling-resource-properties

Lorsque les propriétés sont stockées dans des emplacements (propriétés ou ressources relatives) auxquels les API AEM (Page, Asset) ne peuvent pas accéder directement, les ressources Sling et les ValueMaps peuvent être utilisées pour obtenir les données.

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

Dans ce cas, l’objet AEM peut devoir être converti en Resource Sling pour localiser efficacement la propriété ou la sous-ressource souhaitée.

Page AEM vers Resource Sling

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

Asset AEM vers Resource Sling

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

Écrire des propriétés à l’aide de la ModifiableValueMap de Sling

Utiliser la ModifiableValueMap de Sling pour écrire des propriétés sur des nœuds. Cela permet uniquement d’écrire sur le nœud immédiat (les chemins de propriété relatifs ne sont pas pris en charge).

Notez que l’appel à .adaptTo(ModifiableValueMap.class) nécessite des autorisations d’écriture sur la ressource, sinon elle renvoie null.

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

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

resource.getResourceResolver().commit();

Créer une page AEM

Utilisez toujours PageManager pour créer des pages, car un modèle de page est nécessaire pour définir et initialiser correctement les pages dans 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(); }

Créer une ressource Sling

ResourceResolver prend en charge les opérations de base pour la création de ressources. Lors de la création d’abstractions de niveau supérieur (Pages, Ressources, Balises AEM, etc.), utilisez les méthodes fournies par leurs gestionnaires respectifs.

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();

Supprimer une ressource Sling

ResourceResolver prend en charge la suppression d’une ressource. Lors de la création d’abstractions de niveau supérieur (Pages, Ressources, Balises AEM, etc.), utilisez les méthodes fournies par leurs gestionnaires respectifs.

resourceResolver.delete(resource);

resourceResolver.commit();