Java API Best Practices

Adobe Experience Manager (AEM) bygger på en omfattande programstack med öppen källkod som visar många Java API:er för användning under utveckling. I den här artikeln utforskas de viktigaste API:erna och när och varför de ska användas.

AEM bygger på fyra primära Java API-uppsättningar.

  • Adobe Experience Manager (AEM)

    • Produktabstraktioner som sidor, resurser, arbetsflöden osv.
  • Apache Sling Web Framework

    • REST och resursbaserade abstraktioner som resurser, värdescheman och HTTP-begäranden.
  • JCR (Apache Jackrabbit Oak)

    • Data- och innehållsabstraktioner som nod, egenskaper och sessioner.
  • OSGi (Apache Felix)

    • OSSGi-programbehållarabstraktioner som tjänster och OSGi-komponenter.

Java API-inställningen "rule of thumb"

Den allmänna regeln är att föredra API:erna/abstraktionerna i följande ordning:

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

Om ett API tillhandahålls av AEM föredrar du det framför Sling, JCR och OSGi. Om AEM inte har något API bör du Sling över JCR och OSGi.

Den här ordningen är en allmän regel, vilket innebär undantag. Godtagbara orsaker att bryta mot den här regeln är:

  • Välkända undantag enligt beskrivningen nedan.

  • Nödvändiga funktioner är inte tillgängliga i ett API på högre nivå.

  • Fungerar med befintlig kod (anpassad eller AEM produktkod) som i sin tur använder ett mindre prioriterat API, och kostnaden för att gå över till det nya API:t är obefogad.

    • Det är bättre att konsekvent använda API:t på lägre nivå än att skapa en blandning.

AEM API:er

AEM API:er innehåller abstraktioner och funktioner som är specifika för produkterade användningsfall.

AEM PageManager och Sida API:er innehåller abstraktioner för cq:Page noder i AEM som representerar webbsidor.

Dessa noder är tillgängliga via Sling API:er som resurser och JCR-API:er som noder, AEM API:er innehåller abstraktioner för vanliga användningsområden. Genom att använda AEM API:er kan du säkerställa ett konsekvent beteende mellan AEM av produkten samt anpassningar och tillägg till AEM.

com.adobe.* jämfört med com.day.* API:er

AEM-API:er har en paketintern inställning som identifieras av följande Java-paket, i prioritetsordning:

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

com.adobe.cq stöder produktanvändningsexempel com.adobe.granite har stöd för användning på olika plattformar, t.ex. arbetsflöden eller uppgifter (som används i olika produkter: AEM Assets, Sites osv.).

com.day.cq innehåller "original"-API:er. Dessa API:er åtgärdar viktiga abstraktioner och funktioner som fanns före och/eller runt Adobe förvärv av Day CQ. Dessa API:er stöds och bör inte undvikas om inte com.adobe.cq eller com.adobe.granite tillhandahåller ett (nyare) alternativ.

Nya abstraktioner som Content Fragments och Experience Fragments är inbyggd i com.adobe.cq blanksteg i stället för com.day.cq beskrivs nedan.

Fråga API:er

AEM har stöd för flera frågespråk. De tre huvudspråken är JCR-SQL2, XPath och AEM Query Builder.

Det viktigaste problemet är att ha ett konsekvent frågespråk i hela kodbasen, vilket minskar komplexiteten och gör att du lättare kan förstå kostnaderna.

Alla frågespråk har i princip samma prestandaprofiler som Apache Oak överför dem till JCR-SQL2 för slutlig frågekörning, och konverteringstiden till JCR-SQL2 är försumbar jämfört med själva frågetiden.

Rekommenderat API är AEM Query Builder, som är den högsta nivån för abstraktion och ger ett robust API för att skapa, köra och hämta resultat för frågor, och som ger följande:

FÖRSIKTIGHET

AEM QueryBuilder API läcker ett ResourceResolver-objekt. För att minska läckan följer du detta kodexempel.

Sling API:er

Apache Sling är RESTful-webbramverket som stöder AEM. Sling tillhandahåller routning av HTTP-begäran, modeller av JCR-noder som resurser, ger säkerhetskontext och mycket annat.

Sling API:er har dessutom fördelen att byggas för tillägg, vilket innebär att det ofta är enklare och säkrare att förstärka beteendet i applikationer som byggts med Sling API:er än de mindre utökningsbara JCR-API:erna.

Vanliga användningsområden för Sling API:er

JCR-API:er

The JCR (Java Content Repository) 2.0 API:er ingår i en specifikation för JCR-implementeringar (i AEM fall, Apache Jackrabbit Oak). All JCR-implementering måste följa och implementera dessa API:er, och är därför den lägsta nivån för API för interaktion med AEM.

Själva JCR är en hierarkisk/trädbaserad NoSQL-AEM som används som innehållsdatabas. JCR har en mängd API:er som stöds, från innehålls-CRUD till frågor om innehåll. Trots detta robusta API är det sällan de föredras framför AEM och Sling abstraktioner.

Använd alltid JCR-API:erna framför API:erna för Apache Jackrabbit Oak. JCR-API:erna är för interagera med en JCR-databas, medan Oak API:er är för implementera en JCR-databas.

Vanliga missuppfattningar om JCR-API:er

Även om JCR är AEM innehållsdatabas är dess API:er INTE den föredragna metoden för interaktion med innehållet. Använd i stället AEM API:er (Sida, Resurser, Tagg osv.) eller Sling Resource APIs eftersom de ger bättre abstraktioner.

FÖRSIKTIGHET

En stor användning av JCR-API:ernas Session- och Node-gränssnitt i ett AEM program är kodlukt. Säkerställ Sling API:er bör inte användas i stället.

Vanliga användningsområden för JCR-API:er

OSGi API:er

Det finns liten överlappning mellan OSGi-API:erna och API:erna på den högre nivån (AEM, Sling, och JCR) och behovet av att använda API:er för OSGi är sällsynt och kräver hög AEM utvecklingskompetens.

API:er för OSGi och Apache Felix

OSGi definierar en specifikation som alla OSGi-behållare måste implementera och följa. AEM OSGi-implementering, Apache Felix, innehåller också flera egna API:er.

  • Föredra OSGi-API:er (org.osgi) över API:er för Apache Felix (org.apache.felix).

Vanliga användningsområden för OSGi-API:er

Undantag för regeln

Följande är vanliga undantag till reglerna som definieras ovan.

OSGi API:er

När det gäller OSGi-abstraktioner på låg nivå, som att definiera eller läsa i OSGi-komponentegenskaper, finns de nyare abstreringarna i org.osgi framför Sling-funktioner på högre nivå. De konkurrerande Sling-abstraktionerna har inte markerats som @Deprecated och föreslå org.osgi alternativ.

Observera även att noddefinitionen för OSGi-konfigurationen föredrar cfg.json över sling:OsgiConfig format.

AEM resurs-API:er

  • Föredra com.day.cq.dam.api över com.adobe.granite.asset.api.

    • Med com.day.cq Med Assets API:er får du mer kostnadsfria verktyg för att AEM användningsfall för resurshantering.
    • Granite Assets API:er har stöd för resurshanteringsfall på låg nivå (version, relationer).

Fråga API:er

  • AEM QueryBuilder stöder inte vissa frågefunktioner som förslag, stavningskontroll och indextips bland andra mindre vanliga funktioner. Du bör använda JCR-SQL2 för att fråga med dessa funktioner.

Sling Registrering av serverdel

Sling Filterregistrering

Användbara kodfragment

Nedan följer några praktiska Java-kodfragment som illustrerar de effektivaste strategierna för vanliga användningsområden med hjälp av beskrivna API:er. De här fragmenten visar också hur du går från mindre prioriterade API:er till mer önskade API:er.

JCR-session till Sling ResursResolver

Stänger automatiskt Sling ResourceResolver

Sedan AEM 6.2 har Sling ResourceResolver är AutoClosable i en try-with-resources -programsats. Med den här syntaxen anropas resourceResolver .close() behövs inte.

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

Manuellt stängd Sling ResourceResolver

ResourceResolvers kan bara stängas manuellt i en finally om tekniken för automatisk stängning som visas ovan inte kan användas.

@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-sökväg till Sling Resource

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

JCR-nod till Sling Resource

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

Sling Resource till AEM

Rekommenderad metod

DamUtil.resolveToAsset(..)löser alla resurser under dam:Asset till objektet Asset genom att gå upp i trädet efter behov.

Asset asset = DamUtil.resolveToAsset(resource);

Alternativ metod

Att anpassa en resurs till en resurs kräver att själva resursen är dam:Asset nod.

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

Sling Resurs till AEM

Rekommenderad metod

pageManager.getContainingPage(..) löser alla resurser under cq:Page till objektet Page genom att gå upp i trädet efter behov.

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

Alternativ metod

Att anpassa en resurs till en sida kräver att själva resursen är cq:Page nod.

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

AEM sidegenskaper

Använd get-metoder för sidobjektet för att få välkända egenskaper (getTitle(), getDescription(), osv.) och page.getProperties() för att få [cq:Page]/jcr:content ValueMap för att hämta andra egenskaper.

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

Läs AEM Resursmetadataegenskaper

Resurs-API:t innehåller praktiska metoder för att läsa egenskaper från [dam:Asset]/jcr:content/metadata nod. Observera att detta inte är en ValueMap. Den andra parametern (standardvärde och datatypsbyte) stöds inte.

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

Läs Sling Resource egenskaper

När egenskaper lagras på platser (egenskaper eller relativa resurser) där AEM-API:erna (Sida, Resurs) inte har direktåtkomst, Sling Resurser och ValueMaps kan användas för att hämta data.

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

I det här fallet kan AEM-objektet behöva konverteras till Sling Resource för att effektivt hitta önskad egenskap eller underresurs.

AEM sida till Sling Resource

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

AEM resurs till Sling Resource

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

Skriv egenskaper med Sling's ModiitableValueMap

Använd Sling's ModiitableValueMap för att skriva egenskaper till noder. Detta kan bara skriva till den omedelbara noden (relativa egenskapssökvägar stöds inte).

Anteckna samtalet till .adaptTo(ModifiableValueMap.class) kräver skrivbehörighet för resursen, annars returneras null.

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

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

resource.getResourceResolver().commit();

Skapa en AEM sida

Använd alltid PageManager för att skapa sidor när en sidmall används, vilket krävs för att definiera och initiera sidor i 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(); }

Skapa en Sling Resurs

ResourceResolver stöder grundläggande åtgärder för att skapa resurser. När du skapar abstraktioner på högre nivå (AEM sidor, resurser, taggar osv.) använda de metoder som deras respektive chefer tillhandahåller.

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

Ta bort en Sling Resurs

ResourceResolver stöder borttagning av en resurs. När du skapar abstraktioner på högre nivå (AEM sidor, resurser, taggar osv.) använda de metoder som deras respektive chefer tillhandahåller.

resourceResolver.delete(resource);

resourceResolver.commit();

På denna sida