Using Sling Adapters using-sling-adapters

CAUTION
AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

Sling offers an Adapter pattern to conveniently translate objects that implement the Adaptable interface. This interface provides a generic adaptTo() method that will translate the object to the class type being passed as the argument.

For example to translate a Resource object to the corresponding Node object, you can simply do:

Node node = resource.adaptTo(Node.class);

Use Cases use-cases

There are the following use cases:

  • Get implementation-specific objects.

    For example, a JCR-based implementation of the generic Resource interface provides access to the underlying JCR Node.

  • Shortcut creation of objects that require internal context objects to be passed.

    For example, the JCR-based ResourceResolver holds a reference to the request’s JCR Session, which in turn is needed for many objects that will work based on that request session, such as the PageManager or UserManager.

  • Shortcut to services.

    A rare case - sling.getService() is simple as well.

Null Return Value null-return-value

adaptTo() can return null.

There are various reasons for this, including:

  • the implementation does not support the target type
  • an adapter factory handling this case is not active (eg. due to missing service references)
  • internal condition failed
  • service is not available

It is important that you handle the null case gracefully. For jsp renderings it might be acceptable to have the jsp fail if that will result in an empty piece of content.

Caching caching

To improve performance, implementations are free to cache the object returned from a obj.adaptTo() call. If the obj is the same, the returned object is the same.

This caching is performed for all AdapterFactory based cases.

However, there is no general rule - the object could be either a new instance or an existing one. This means that you cannot rely on either behavior. Hence it is important, especially inside AdapterFactory, that objects are reusable in this scenario.

How it works how-it-works

There are various ways that Adaptable.adaptTo() can be implemented:

  • By the object itself; implementing the method itself and mapping to certain objects.

  • By an AdapterFactory, which can map arbitrary objects.

    The objects must still implement the Adaptable interface and must extend SlingAdaptable (which passes the adaptTo call to a central adapter manager).

    This allows hooks into the adaptTo mechanism for existing classes, such as Resource.

  • A combination of both.

For the first case, the javadocs can state what adaptTo-targets are possible. However, for specific subclasses such as the JCR-based Resource, often this is not possible. In the latter case, implementations of AdapterFactory are typically part of the private classes of a bundle and thus not exposed in a client API, nor listed in javadocs. Theoretically, it would be possible to access all AdapterFactory implementations from the OSGi service runtime and look at their “adaptables” (sources and targets) configurations, but not to map them to each other. In the end, this depends on the internal logic, which must be documented. Hence this reference.

Reference reference

Sling sling

Resource adapts to:

Node
If this is a JCR-node-based resource or a JCR property referencing a node.
Property
If this is a JCR-property-based resource.
Item
If this is a JCR-based resource (node or property).
Map
Returns a map of the properties, if this is a JCR-node-based resource (or other resource supporting value maps).
ValueMap
Returns a convenient-to-use map of the properties, if this is a JCR-node-based resource (or other resource supporting value maps). Can also be achieved (more simply) by using
ResourceUtil.getValueMap(Resource) (handles null case, etc.).
InheritanceValueMap
Extension of ValueMap which allows the hierarchy of resources to be taken into account when looking for properties.
PersistableValueMap
If this is a JCR-node-based resource and the user has permissions to modify properties on that node.
Note: multiple persistable maps do not share their values.
InputStream
Returns the binary content of a "file" resource (if this is a JCR-node-based resource and the node type is nt:file or nt:resource; if this is a bundle resource; file content if this is a file system resource) or the data of a binary JCR property
resource.
URL
Returns a URL to the resource (repository URL of this node if this is a JCR-node-based resource; jar bundle URL if this is a bundle resource; file URL if this is a file system resource).
File
If this is a file system resource.
SlingScript
If this resource is a script (e.g. jsp file) for which a script engine is registered with sling.
Servlet
If this resource is a script (e.g. jsp file) for which a script engine is registered with sling or if this is a servlet resource.
Authorizable
(Jackrabbit)
If this is a an authorizable resource (from the
AuthorizableResourceProvider in org.apache.sling.jackrabbit.usermanager, under /system/userManager).
String
Boolean
Long
Double
Calendar
Value
String[]
Boolean[]
Long[]
Calendar[]
Value[]
Returns the value(s) if this is a JCR-property-based resource (and the value fits).
LabeledResource
If this is a JCR-node-based resource.
Page
If this is a JCR-node-based resource and the node is a cq:Page (or cq:PseudoPage).
Component
If this is a cq:Component node resource.
Design
If this is a design node (cq:Page, typically under
/etc/designs).
Template
If this is a cq:Template node resource.
Blueprint
If this is a cq:Page node resource (more specific checks possible in the future).
Asset
If this is a dam:Asset node resource.
Rendition
If this is a dam:Asset rendition (nt:file under the rendition folder of a dam:Assert)
Tag
If this is a cq:Tag node resource.
Preferences
If this is a cq:Preferences node resource for a valid user/group.
Profile
If this is the profile below a user/group node (eg.
cq/security/components/profile).
UserManager
Based on the JCR session if this is a JCR-based resource and the user has permissions to access the UserManager.
Authorizable
(cq-security)
This is a authorizable home node.
User
(cq-security)
If this is a user home node.
PrivilegeManager
SimpleSearch
Searches below the resource (or use setSearchIn()) if this is a JCR-based resource.
WorkflowStatus
Workflow status for the given page/workflow payload node.
ReplicationStatus
Replication status for the given resource or its jcr:content subnode (checked first).
ConnectorResource
Returns an adapted connector resource for certain types, if this is a JCR-node-based resource.
Config
If this is a cq:ContentSyncConfig node resource.
ConfigEntry
If this is below a cq:ContentSyncConfig node resource.

ResourceResolver adapts to:

Session
The request's JCR session, if this is a JCR-based resource resolver (default).
PageManager
ComponentManager
Designer
AssetManager
Based on the JCR session, if this is a JCR-based resource resolver.
TagManager
Based on the JCR session, if this is a JCR-based resource resolver.
UserManager
Based on the JCR session, if this is a JCR-based resource resolver, and if the user has permissions to access the UserManager.
Authorizable
The current user.
User
The current user.
PrivilegeManager
Preferences
Preferences of the current user (based on JCR session if this is a JCR-based resource resolver).
PreferencesService
PinManager
QueryBuilder
Externalizer
For externalizing absolute URLs, even with out the request object.

SlingHttpServletRequest adapts to:

No targets yet, but implements Adaptable and could be used as source in a custom AdapterFactory.

SlingHttpServletResponse adapts to:

ContentHandler
(XML)
If this is a sling rewriter response.

WCM wcm

Page adapts to:

Resource
Resource of the page.
LabeledResource
Labeled resource (== this).
Node
Node of the page.
...
Everything that the page's resource can be adapted to.

Component adapts to:

Resource
Resource of the component.
LabeledResource
Labeled resource (== this).
Node
Node of the component.
Everything that the component’s resource can be adapted to.

Template adapts to:

Resource
Resource of the template.
LabeledResource
Labeled resource (== this).
Node
Node of this template.
...
Everything that the template's resource can be adapted to.

Security security

Authorizable, User and Group adapt to:

Node
Returns the user/group home node.
ReplicationStatus
Returns the replication status for the user/group home node.

DAM dam

Asset adapts to:

Resource
Resource of the asset.
Node
Node of the asset.
Everything that the asset’s resource can be adapted to.

Tagging tagging

Tag adapts to:

Resource
Resource of the tag.
Node
Node of the tag.
Everything that the tag’s resource can be adapted to.

Other other

Furthermore Sling / JCR / OCM also provides an [AdapterFactory](https://sling.apache.org/site/adapters.html#Adapters-AdapterFactory) for custom OCM (Object Content Mapping) objects.

recommendation-more-help
2315f3f5-cb4a-4530-9999-30c8319c520e