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.

Java™ API-inställning för"tumregel"

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

Om ett API anges av AEM bör du föredra det framför Sling, JCR och OSGi. Om AEM inte tillhandahåller ett API bör du föredra Sling framför 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:

AEM API:er

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

AEM PageManager - och Page -API:er innehåller till exempel 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, men 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 och anpassningar och tillägg till AEM.

com.adobe.* vs com.day.* API:er

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

Paketet com.adobe.cq har stöd för produktanvändningsfall, medan com.adobe.granite har stöd för flerproduktsplattformsanvändning, som arbetsflöde eller uppgifter (som används för olika produkter: AEM Assets, Sites, osv.).

Paketet com.day.cq innehåller ursprungliga 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 undvikas, såvida inte com.adobe.cq- eller com.adobe.granite-paketen inte har ett (nyare) alternativ.

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

Fråga API:er

AEM stöder 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, eftersom Apache Oak kopplar 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.

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

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 skapas för tillägg, vilket innebär att det ofta är enklare och säkrare att förstärka beteendet för program som skapats med Sling API:er än de mindre utökningsbara JCR-API:erna.

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

JCR-API:er

JCR-API:erna (Java™ Content Repository) 2.0 ingår i en specifikation för JCR-implementeringar (för AEM 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 innehåll.

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 det här robusta API:t är det sällan de föredras framför AEM på högre nivå och Sling-abstraktioner.

Använd alltid JCR-API:erna framför API:erna i Apache Jackrabbit Oak. JCR-API:erna är till för interaktion med en JCR-databas, medan Oak-API:erna är till för implementering av en JCR-databas.

Vanliga missuppfattningar om JCR-API:er

Även om JCR AEM innehållsdatabasen är dess API:er INTE den bästa metoden för interaktion med innehållet. Använd i stället AEM API:er (Page, Assets, Tag o.s.v.) eller Sling Resource API:er så att de ger bättre abstraktioner.

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

OSGi API:er

Det finns liten överlappning mellan API:erna för OSGi och API:er på högre nivå (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.

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 du hanterar OSGi-abstreringar på låg nivå, som att definiera eller läsa i OSGi-komponentegenskaper, föredras de nyare abstreringarna från org.osgi framför Sling-abstraktioner på högre nivå. Motsvarande Sling-abstractions har inte markerats som @Deprecated och föreslår alternativet org.osgi.

Observera också att noddefinitionen för OSGi-konfigurationen föredrar cfg.json framför formatet sling:OsgiConfig.

AEM resurs-API:er

Fråga API:er

Sling servletregistrering sling-servlet-registration

Sling Filterregistrering sling-filter-registration

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 ResourceResolver

Automatisk stängning av Sling ResourceResolver

Sedan AEM 6.2 är Sling ResourceResolver AutoClosable i en try-with-resources -sats. Med den här syntaxen behövs inget explicit anrop till resourceResolver .close().

@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 stängas manuellt i ett finally-block om det inte går att använda tekniken som visas ovan.

@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 att AEM resurs

Rekommenderad metod

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

Asset asset = DamUtil.resolveToAsset(resource);

Alternativ metod

Om du anpassar en resurs till en resurs måste själva resursen vara noden dam:Asset.

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

Sling resurs till AEM sida

Rekommenderad metod

pageManager.getContainingPage(..) löser alla resurser under cq:Page till sidobjektet genom att gå uppåt 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 alternative-approach-1

Om du anpassar en resurs till en sida måste själva resursen vara noden cq:Page.

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

AEM sidegenskaper

Använd Page-objektets get-metoder för att hämta välkända egenskaper (getTitle(), getDescription() o.s.v.) och page.getProperties() för att hämta [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 noden [dam:Asset]/jcr:content/metadata. Detta är inte 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 read-sling-resource-properties

När egenskaper lagras på platser (egenskaper eller relativa resurser) där AEM-API:erna (Sida, Tillgång) inte kan komma åt direkt, kan Sling-resurserna och ValueMaps 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 måste AEM-objektet 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);

Skriva egenskaper med ModiitableValueMap för Sling

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

Observera att anropet 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

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 har stöd för grundläggande åtgärder för att skapa resurser. När du skapar abstraktioner på högre nivå (AEM sidor, Assets, taggar och så vidare) använder du de metoder som deras respektive hanterare 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, Assets, taggar och så vidare) använder du de metoder som deras respektive hanterare tillhandahåller.

resourceResolver.delete(resource);

resourceResolver.commit();