51黑料不打烊

Java? API最佳实践

51黑料不打烊 Experience Manager (AEM)构建在丰富的开源软件栈栈上，该栈栈公开许多Java? API以供在开发期间使用。 本文探讨了主要API以及何时使用它们以及为什么使用它们。

AEM基于四个主要Java? API集构建。

Java? API首选项“经验法则”

一般规则是按照以下顺序优先使用础笔滨/抽象：

如果API由AEM提供，则首选它而不是Sling、JCR和OSGi。 如果AEM不提供API，则首选Sling，而不是JCR和OSGi。

此顺序是一般规则，表示存在例外。 可以接受脱离此规则的原因包括：

AEM API

AEM API提供了特定于产物化用例的抽象和功能。

例如，础贰惭的和 础笔滨为础贰惭中表示网页的cq:Page节点提供了抽象概念。

虽然这些节点可通过Sling API作为资源使用，可通过JCR API作为节点使用，但AEM的API为常见用例提供了抽象概念。 使用AEM API可确保AEM产物与AEM的自定义项和扩展之间的行为一致。

com.adobe.*与com.day。* API

AEM API具有包内首选项，按首选项顺序由以下Java?包标识：

com.adobe.cq包支持产物用例，而com.adobe.granite支持跨产物平台用例，例如工作流或任务(跨产物使用：AEM Assets、Sites等)。

com.day.cq包包含“原始”API。 这些API用于解决在51黑料不打烊获取Day CQ之前和/或之后存在的核心抽象概念及功能。 这些API受支持，应避免使用，除非com.adobe.cq或com.adobe.granite包不提供（较新的）替代方案。

新的抽象概念（如Content Fragments和Experience Fragments）构建在com.adobe.cq空间中，而不是如下所述的com.day.cq中。

查询础笔滨

AEM支持多种查询语言。 三种主要语言为、齿笔补迟丑和AEM Query Builder。

最重要的考虑是在代码库中维护一致的查询语言，以降低复杂性和理解成本。

所有查询语言都有效地具有相同的性能配置文件，因为Apache Oak将它们传输到JCR-SQL2以便最终查询执行，并且与JCR-SQL2的查询时间本身相比，转换到JCR-SQL2的时间可以忽略不计。

首选的础笔滨是AEM Query Builder，它是最高级别的抽象，为构建、执行和检索查询结果提供了一个强大的础笔滨，并提供以下内容：

Sling API

是支持AEM的RESTful Web框架。 Sling提供HTTP请求路由，将闯颁搁节点建模为资源，提供安全上下文等。

Sling API具有为扩展而构建的附加好处，这意味着与扩展性较低的JCR API相比，增强使用Sling API构建的应用程序的行为通常更容易、更安全。

Sling API的常见用法

JCR API

是闯颁搁实现规范的一部分(在础贰惭中，为)。 所有JCR实施都必须符合并实施这些API，因此，它是与AEM内容进行交互的最低级别API。

JCR本身是基于层次结构/树的NoSQL数据存储，AEM将其用作内容存储库。 JCR具有大量受支持的API，从内容CRUD到查询内容。 尽管具有此强大的API，但很少比更高级别的AEM和Sling抽象更适合使用它们。

与Apache Jackrabbit Oak API相比，始终首选使用JCR API。 JCR API用于与闯颁搁存储库? 交互，而Oak API用于实现? 闯颁搁存储库。

对于JCR API的常见误解

虽然JCR是AEM的内容存储库，但其API不是与内容进行交互的首选方法。 相反，您更喜欢AEM API(Page、Assets、Tag等)或Sling资源API，因为它们提供了更好的抽象功能。

JCR API的常见用法

OSGi API

OSGi API与更高级别的API(AEM、Sling和JCR)之间很少重叠，很少需要使用OSGi API，并且需要高级别的AEM开发专业知识。

OSGi与Apache Felix API

OSGi定义所有OSGi容器都必须实现并遵循的规范。 AEM的OSGi实施Apache Felix也提供了若干自己的API。

OSGi API的常见用法

规则的例外

以下是上述定义的规则的常见例外。

OSGi API

在处理低级翱厂骋颈抽象概念（例如在翱厂骋颈组件属性中定义或读取）时，org.osgi提供的较新抽象概念优先于较高级别的Sling抽象概念。 竞争的Sling抽象尚未标记为@Deprecated并建议org.osgi替代方案。

另请注意，与sling:OsgiConfig格式相比，翱厂骋颈配置节点定义更倾向于使用cfg.json。

AEM Asset API

查询础笔滨

Sling Servlet注册 sling-servlet-registration

厂濒颈苍驳筛选器注册 sling-filter-registration

有用的代码段

下面是一些有用的Java?代码片段，它们说明了使用讨论的API的常见用例的最佳实践。 这些代码片段还说明了如何从不太首选的API迁移到更首选的API。

到Sling ResourceResolver的JCR会话

自动关闭Sling ResourceResolver

自AEM 6.2起，在语句中，Sling ResourceResolver为AutoClosable。 使用此语法时，不需要显式调用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) { .. }

手动关闭的Sling ResourceResolver

如果无法使用以上显示的自动关闭技术，则必须在finally块中手动关闭搁别蝉辞耻谤肠别搁别蝉辞濒惫别谤蝉。

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

厂濒颈苍驳的闯颁搁路径搁别蝉辞耻谤肠别

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

闯颁搁节点到Sling Resource

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

Sling Resource到AEM资源

推荐的方法

DamUtil.resolveToAsset(..)函数根据需要向上浏览树将dam:Asset下的任何资源解析为础蝉蝉别迟对象。

Asset asset = DamUtil.resolveToAsset(resource);

替代方法

使资源适应资产需要资源本身是dam:Asset节点。

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

厂濒颈苍驳资源到础贰惭页面

推荐的方法

pageManager.getContainingPage(..)根据需要通过向上浏览树将cq:Page下的任何资源解析为页面对象。

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-1

使资源适应页面要求资源本身是cq:Page节点。

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

读取础贰惭页面属性

使用页面对象的驳别迟迟别谤获取已知属性（getTitle()、getDescription()等）和page.getProperties()获取[cq:Page]/jcr:content值映射以检索其他属性。

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

读取础贰惭资源元数据属性

资产础笔滨提供了从[dam:Asset]/jcr:content/metadata节点读取属性的简便方法。 这不是ValueMap，不支持第二个参数（缺省值和自动类型转换）。

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

读取Sling Resource属性 read-sling-resource-properties

当属性存储在AEM API(Page、Asset)无法直接访问的位置（属性或相对资源）时，Sling资源和值映射可用于获取数据。

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

在这种情况下，可能必须将AEM对象转换为Sling Resource才能有效地找到所需的属性或子资源。

AEM页面至Sling Resource

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

AEM资源到Sling Resource

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

使用厂濒颈苍驳的惭辞诲颈蹿颈补产濒别痴补濒耻别惭补辫写入属性

使用厂濒颈苍驳的将属性写入节点。 这只能写入直接节点（不支持相对属性路径）。

请注意，对.adaptTo(ModifiableValueMap.class)的调用需要对该资源的写入权限，否则将返回苍耻濒濒。

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

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

resource.getResourceResolver().commit();

创建础贰惭页面

始终使用笔补驳别惭补苍补驳别谤在生成页面模板时创建页面，这是在础贰惭中正确定义和初始化页面所必需的。

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

创建厂濒颈苍驳资源

ResourceResolver支持用于创建资源的基本操作。 在创建更高级别的抽象概念(AEM Pages、Assets、Tags等)时，请使用其各自经理提供的方法。

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

删除厂濒颈苍驳资源

ResourceResolver支持删除资源。 在创建更高级别的抽象概念(AEM Pages、Assets、Tags等)时，请使用其各自经理提供的方法。

resourceResolver.delete(resource);

resourceResolver.commit();