Author: kwin
Date: Sun Apr 2 06:59:47 2017
New Revision: 1789857
URL: http://svn.apache.org/viewvc?rev=1789857&view=rev
Log:
SLING-2295, SLING-2313 document web console for adapters and according metadata
format of the SLING-INF/adapters.json
Modified:
sling/site/trunk/content/documentation/the-sling-engine/adapters.mdtext
Modified:
sling/site/trunk/content/documentation/the-sling-engine/adapters.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/adapters.mdtext?rev=1789857&r1=1789856&r2=1789857&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/adapters.mdtext
(original)
+++ sling/site/trunk/content/documentation/the-sling-engine/adapters.mdtext Sun
Apr 2 06:59:47 2017
@@ -1,11 +1,13 @@
Title: Adapters
+[TOC]
+
The `Resource` and `ResourceResolver` interfaces are defined with a method
`adaptTo`, which adapts the object to other classes. Using this mechanism the
JCR session of the resource resolver calling the `adaptTo` method with the
`javax.jcr.Session` class object. Likewise the JCR node on which a resource is
based can be retrieved by calling the `Resource.adaptTo` method with the
`javax.jcr.Node` class object.
To use resources as scripts, the `Resource.adaptTo` method must support being
called with the `org.apache.sling.api.script.SlingScript` class object. But of
course, we do not want to integrate the script manager with the resource
resolver. To enable adapting objects to classes which are not foreseen by the
original implementation, a factory mechanism is used. This way, the script
manager can provide an adapter factory to adapt `Resource` to `SlingScript`
objects.
-## Adaptable
+# Adaptable
The `Adaptable` interface defines the API to be implemented by a class
providing adaptability to another class. The single method defined by this
interface is
@@ -34,8 +36,42 @@ The `Adaptable` interface defines the AP
This method is called to get a view of the same object in terms of another
class. Examples of implementations of this method are the Sling
`ResourceResolver` implementation providing adapting to a JCR session and the
Sling JCR based `Resource` implementation providing adapting to a JCR node.
+# Listing Adaptation Possibilities
+
+The Web Console Plugin at `/system/console/adapters` and at
`/system/console/status-adapters` can be used to list all existing adaptables
in the system with their according adapter classes.
+
+The web console plugin evaluates metadata being provided by any
`AdapterFactory` services as well as metadata being provided through the file
`SLING-INF/adapters.json`
+
+# Implementing Adaptable
+
+Each adaptable should derive from `SlingAdaptable` to automatically profit
from all according `AdapterFactories` registered in the system.
+In case the `adaptTo(...)` method is being overwritten an according
`SLING-INF/adapters.json` should be included in the providing bundle
+listing all adaptation possibilities. While this file is not strictly
necessary for the actual adaptation to work, it provides useful information to
the Web Console plugin.
+Otherwise developers will not know which adaptations are supported. The format
of this JSON file looks like this
([SLING-2295](https://issues.apache.org/jira/browse/SLING-2295)):
+
+ {
+ <fully qualified class name of adaptable> : {
+ <condition> : <fully qualified class name of adapter, may be a JSON
array>
+ }
+ }
+
+For example
+
+ {
+ "org.apache.sling.api.resource.Resource" : {
+ "If the adaptable is a AuthorizableResource." : [
+ "java.util.Map",
+ "org.apache.sling.api.resource.ValueMap",
+ "org.apache.jackrabbit.api.security.user.Authorizable"
+ ],
+ "If the resource is an AuthorizableResource and represents a JCR User"
: "org.apache.jackrabbit.api.security.user.User",
+ "If the resource is an AuthorizableResource and represents a JCR
Group" : "org.apache.jackrabbit.api.security.user.Group"
+ }}
+
+Instead of manually creating that JSON file, the annotations from the module
[adapter-annotations](https://svn.apache.org/viewvc/sling/trunk/tooling/maven/adapter-annotations/)
can be used together with the goal `generate-adapter-metadata` from the
[Maven Sling
Plugin](http://sling.apache.org/components/maven-sling-plugin/generate-adapter-metadata-mojo.html)
to generate it automatically
([SLING-2313](https://issues.apache.org/jira/browse/SLING-2313)).
+
-## Extending Adapters
+# Extending Adapters
Sometimes an `Adaptable` implementation cannot foresee future uses and
requirements. To cope with such extensibility requirements two interfaces and
an abstract base class are defined:
@@ -76,7 +112,7 @@ The `AdapterFactory` interface defines t
Class<AdapterType> type);
-Implementations of this interface are registered as OSGi services providing
two lists: The list of classes which may be adapted (property named
*adaptables*) and the list of classes to which the adapted class may be adapted
(property named *adapters*). A good example of an Class implementing
`AdapterFactory` is the `SlingScriptAdapterFactory`.
+Implementations of this interface are registered as OSGi services providing
two lists: The list of classes which may be adapted (property named
`adaptables`) and the list of classes to which the adapted class may be adapted
(property named `adapters`). A good example of an Class implementing
`AdapterFactory` is the `SlingScriptAdapterFactory`. In addition a property
named `adapter.condition` can be provided which is supposed to contain a string
value explaining under which circumstances the adaption will work (if there are
any restrictions). This is evaluated by the Web Console Plugin.
`AdapterFactory` services are gathered by a `AdapterManager` implementation
for use by consumers. Consumers should not care for `AdapterFactory` services.
