SLING-2938 - Provide Javadoc for the Sling Adapter annotations
diff --git a/pom.xml b/pom.xml
index 3400e59..b89de64 100644
--- a/pom.xml
+++ b/pom.xml
@@ -53,7 +53,13 @@
<dependency>
<groupId>org.osgi</groupId>
<artifactId>org.osgi.service.component</artifactId>
- <version>1.4.0</version><!-- for link in javadoc to default property types/annotations -->
+ <version>1.4.0</version><!-- For link in Javadoc to default property types/annotations -->
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>org.apache.sling.api</artifactId>
+ <version>2.11.0</version><!-- For link in Javadoc to AdapterFactory- & AdapterManager-class -->
<scope>provided</scope>
</dependency>
<dependency>
diff --git a/src/main/java/org/apache/sling/adapter/annotations/AdapterCondition.java b/src/main/java/org/apache/sling/adapter/annotations/AdapterCondition.java
index b588194..f3e261e 100644
--- a/src/main/java/org/apache/sling/adapter/annotations/AdapterCondition.java
+++ b/src/main/java/org/apache/sling/adapter/annotations/AdapterCondition.java
@@ -16,9 +16,26 @@
*/
package org.apache.sling.adapter.annotations;
+import org.apache.sling.api.adapter.AdapterFactory;
import org.osgi.service.component.annotations.ComponentPropertyType;
+/**
+ * Component Property Type (as defined by OSGi DS 1.4) for the condition for Sling Adapters.
+ * Takes care of writing the service property <code>adapter.condition</code>.
+ * <p>
+ * The use of this annotation will only have an effect if used in conjunction with the {@link SlingAdapter}
+ * annotation, which defines properties that are required for an {@link AdapterFactory} to be picked up.
+ * <p>
+ * Use this annotation to specify the condition under which the adaption will take place. The
+ * main use-case for annotating a class with this annotation, is when the result of the adaption
+ * could be <code>null</code>.
+ */
@ComponentPropertyType
public @interface AdapterCondition {
+ /**
+ * Specifies the condition under which this adaption takes place. The most common way to do this
+ * is to use a language such as "If the ... is a ...", "If the adaptable ...", etc.
+ * @return The condition under which this adaption takes place
+ */
String value();
}
diff --git a/src/main/java/org/apache/sling/adapter/annotations/AdapterDeprecated.java b/src/main/java/org/apache/sling/adapter/annotations/AdapterDeprecated.java
index c118398..b2c2992 100644
--- a/src/main/java/org/apache/sling/adapter/annotations/AdapterDeprecated.java
+++ b/src/main/java/org/apache/sling/adapter/annotations/AdapterDeprecated.java
@@ -16,8 +16,20 @@
*/
package org.apache.sling.adapter.annotations;
+import org.apache.sling.api.adapter.AdapterFactory;
import org.osgi.service.component.annotations.ComponentPropertyType;
+/**
+ * Component Property Type (as defined by OSGi DS 1.4) for the condition for Sling Adapters.
+ * Takes care of writing the service property <code>adapter.deprecated</code>.
+ * <p>
+ * The use of this annotation will only have an effect if used in conjunction with the {@link SlingAdapter}
+ * annotation, which defines properties that are required for an {@link AdapterFactory} to be picked up.
+ * <p>
+ * Use this annotation to mark the adapter as deprecated. The only consequence of setting this property
+ * is an indication in the Web Console Plugin, where it is made apparent to a developer that the use
+ * of this adapter is deprecated and may not work anymore in the future.
+ */
@ComponentPropertyType
public @interface AdapterDeprecated {
}
diff --git a/src/main/java/org/apache/sling/adapter/annotations/SlingAdapter.java b/src/main/java/org/apache/sling/adapter/annotations/SlingAdapter.java
index 9dab9a7..b9ab53b 100644
--- a/src/main/java/org/apache/sling/adapter/annotations/SlingAdapter.java
+++ b/src/main/java/org/apache/sling/adapter/annotations/SlingAdapter.java
@@ -16,11 +16,53 @@
*/
package org.apache.sling.adapter.annotations;
+import org.apache.sling.api.adapter.AdapterFactory;
+import org.apache.sling.api.adapter.AdapterManager;
import org.osgi.service.component.annotations.ComponentPropertyType;
+import org.osgi.service.component.propertytypes.ServiceRanking;
+/**
+ * Component Property Type (as defined by OSGi DS 1.4) for Sling Adapters.
+ * Takes care of writing the service properties, that can be found as constants in {@link AdapterFactory}.
+ * The annotated component will be registered as a Sling adapter, using its minimum required configuration.
+ * <p>
+ * Due to technical limitations, it is possible to set either of the values to an empty array, in which
+ * case the adapter registration will not be picked up by the framework. Extra care must be taken by the
+ * developer to ensure that both values will are entered correctly.
+ * <p>
+ * If multiple implementations for the same combination of adapter and adaptable are registered,
+ * the implementation with the lowest <code>service.ranking</code>-property wins. This property can be set
+ * through the use of the {@link ServiceRanking} Component Property Type annotation.
+ * <p>
+ * The services defined through this annotation will be picked up by the {@link AdapterManager}, which is
+ * responsible for honoring the <code>service.ranking</code> when multiple matching factories are found.
+ * <p>
+ * Warning: It is up to the implementation of the annotated class to handle the adaption properly:
+ * <ul>
+ * <li>It is up to the implementation to always return the same object for the adaptable, or not;</li>
+ * <li>It is up to the implementation to handle all combinations of the specified adaptables and adapters;</li>
+ * <li>The adaptTo()-method's <code>type</code>-parameter can be used to check the adapter-type requested;</li>
+ * <li>If the adaptTo()-method can return null, <code>adapter.condition</code> should be set to indicate this.</li>
+ * </ul>
+ * <p>
+ * For the registration of the other related service properties, see also {@link AdapterCondition} and the
+ * lesser used {@link AdapterDeprecated}.
+ *
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/adapters.html">Sling Adapters</a>
+ */
@ComponentPropertyType
public @interface SlingAdapter {
+ /**
+ * Specifies the adaptables for which this adapter will be called. For each adaptable specified, this
+ * adapter will be called to request a result of any of the specified adapters.
+ * @return The classes that can be used as an adaptable
+ */
Class<?>[] adaptables();
+ /**
+ * Specifies the adapters for which this adapter will be called, but only if the source adaptable matches
+ * any of the specified adaptables.
+ * @return The classes that this adapter can adapt to
+ */
Class<?>[] adapters();
}
