sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1067426 - in /sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter: Adaptable.java AdapterFactory.java AdapterManager.java SlingAdaptable.java
Date Sat, 05 Feb 2011 10:53:02 GMT
Author: fmeschbe
Date: Sat Feb  5 10:53:02 2011
New Revision: 1067426

URL: http://svn.apache.org/viewvc?rev=1067426&view=rev
Log:
SLIJNG-1967 JavaDoc improvements; most importantly the behaviour of returning the same or
different instances on each call to the Adaptable.adaptTo method is clarified

Modified:
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/Adaptable.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterFactory.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterManager.java
    sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/SlingAdaptable.java

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/Adaptable.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/Adaptable.java?rev=1067426&r1=1067425&r2=1067426&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/Adaptable.java (original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/Adaptable.java Sat
Feb  5 10:53:02 2011
@@ -18,15 +18,31 @@
  */
 package org.apache.sling.api.adapter;
 
+/**
+ * The <code>Adaptable</code> interface identifies objects which can be adapted
+ * to other types or representations of the same object. For example a JCR Node
+ * based {@link org.apache.sling.api.resource.Resource} can adapt to the
+ * underlying JCR Node or a file based resource could adapt to the underlying
+ * <code>java.io.File</code>.
+ */
 public interface Adaptable {
 
     /**
      * Adapts the adaptable to another type.
+     * <p>
+     * Please not that it is explicitly left as an implementation detail whether
+     * each call to this method with the same <code>type</code> yields the same
+     * object or a new object on each call.
+     * <p>
+     * Implementations of this method should document their adapted types as
+     * well as their behaviour with respect to returning newly created or not
+     * instance on each call.
      *
      * @param <AdapterType> The generic type to which this resource is adapted
      *            to
      * @param type The Class object of the target type, such as
-     *            <code>Node.class</code>
+     *            <code>javax.jcr.Node.class</code> or
+     *            <code>java.io.File.class</code>
      * @return The adapter target or <code>null</code> if the resource cannot
      *         adapt to the requested type
      */

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterFactory.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterFactory.java?rev=1067426&r1=1067425&r2=1067426&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterFactory.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterFactory.java
Sat Feb  5 10:53:02 2011
@@ -26,21 +26,26 @@ package org.apache.sling.api.adapter;
  * used by the {@link AdapterManager} to adapt objects on demand. The
  * <code>AdapterFactory</code> services are not really intended to be used by
  * clients directly.
+ * <p>
+ * The {@link AdapterManager} implementations ensures that the
+ * {@link #getAdapter(Object, Class)} method is only called for the combination
+ * of adaptable and adapter type which is allowed as per the service
+ * registration properties {@link #ADAPTABLE_CLASSES} and
+ * {@link #ADAPTER_CLASSES}.
  */
 public interface AdapterFactory {
 
     /**
      * The service name to use when registering implementations of this
-     * interface as services (value is
-     * "org.apache.sling.osgi.commons.AdapterFactory").
+     * interface as services.
      */
-    String SERVICE_NAME = AdapterFactory.class.getName();
+    String SERVICE_NAME = "org.apache.sling.api.adapter.AdapterFactory";
 
     /**
      * The service registration property listing the fully qualified names of
      * classes which can be adapted by this adapter factory (value is
      * "adaptables"). The "adaptable" parameters of the
-     * {@link #getAdapter(Object, Class)} method must be an instance of any of
+     * {@link #getAdapter(Object, Class)} method must be an instance of one of
      * these classes for this factory to be able to adapt the object.
      */
     String ADAPTABLE_CLASSES = "adaptables";
@@ -55,10 +60,10 @@ public interface AdapterFactory {
      * Adapt the given object to the adaptable type. The adaptable object is
      * guaranteed to be an instance of one of the classes listed in the
      * {@link #ADAPTABLE_CLASSES} services registration property. The type
-     * parameter is on of the classes listed in the {@link #ADAPTER_CLASSES}
+     * parameter is one of the classes listed in the {@link #ADAPTER_CLASSES}
      * service registration properties.
      * <p>
-     * This method may return <code>null</code> if the adaptable object may not
+     * This method may return <code>null</code> if the adaptable object cannot
      * be adapted to the adapter (target) type for any reason. In this case, the
      * implementation should log a message to the log facility noting the cause
      * for not being able to adapt.

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterManager.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterManager.java?rev=1067426&r1=1067425&r2=1067426&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterManager.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/AdapterManager.java
Sat Feb  5 10:53:02 2011
@@ -22,20 +22,30 @@ package org.apache.sling.api.adapter;
  * The <code>AdapterManager</code> defines the service interface for a manager
  * for object adaption. The adapter manager coordinates the registered
  * {@link AdapterFactory} services on behalf of clients wishing to adapt objects
- * to other types. One such client is the {@link Adaptable} class, which uses
- * the implementation of this bundle to adapt "itself".
+ * to other types. One such client is the {@link SlingAdaptable} class, which
+ * uses the implementation of this bundle to adapt "itself".
+ * <p>
+ * Clients may either extend from the {@link SlingAdaptable} class or access the
+ * <code>AdapterManager</code> service from the OSGi service registry to adapt
+ * objects to other types.
  * <p>
  * This interface is not intended to be implemented by clients.
  */
 public interface AdapterManager {
 
     /**
+     * The name under which this service is registered with the OSGi service
+     * registry.
+     */
+    String SERVICE_NAME = "org.apache.sling.api.adapter.AdapterManager";
+
+    /**
      * Returns an adapter object of the requested <code>AdapterType</code> for
      * the given <code>adaptable</code> object.
      * <p>
      * The <code>adaptable</code> object may be any non-<code>null</code>
object
      * and is not required to implement the <code>Adaptable</code> interface.
-     * 
+     *
      * @param <AdapterType> The generic type of the adapter (target) type.
      * @param adaptable The object to adapt to the adapter type.
      * @param type The type to which the object is to be adapted.

Modified: sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/SlingAdaptable.java
URL: http://svn.apache.org/viewvc/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/SlingAdaptable.java?rev=1067426&r1=1067425&r2=1067426&view=diff
==============================================================================
--- sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/SlingAdaptable.java
(original)
+++ sling/trunk/bundles/api/src/main/java/org/apache/sling/api/adapter/SlingAdaptable.java
Sat Feb  5 10:53:02 2011
@@ -22,14 +22,13 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * The <code>SlingAdaptable</code> class is an (abstract) default
- * implementation of the <code>Adaptable</code> interface. It just uses the
- * default {@link org.apache.sling.api.adapter.AdapterManager} implemented
- * to adapt itself to the requested type.
+ * The <code>SlingAdaptable</code> class is an (abstract) default implementation
+ * of the <code>Adaptable</code> interface. It just uses the default
+ * {@link AdapterManager} implemented to adapt itself to the requested type.
  * <p>
  * Extensions of this class may overwrite the {@link #adaptTo(Class)} method
- * using their own knowledge of adapters and may call this base class
- * implementation to fall back to an extended adapters.
+ * using their own knowledge of adapters and should call this base class
+ * implementation to fall back for other types.
  *
  * @since 2.2
  */
@@ -39,24 +38,27 @@ public abstract class SlingAdaptable imp
     private static volatile AdapterManager ADAPTER_MANAGER;
 
     /**
-     * Set the adapter manager to be used by a synthetic resource. A bundle
-     * implementing the adapter manager can set the manager through this method.
-     * The set adapter manager will be used in the {@link #adaptTo(Class)}
-     * method of a synthetic resource.
+     * Sets the global {@link AdapterManager} to be used by this class.
+     * <p>
+     * This method is intended to only be called by the {@link AdapterManager}
+     * wanting to register itself for use. Currently only a single adapter
+     * manager is supported by this class.
      *
-     * @param adapterMgr The adapter manager.
+     * @param adapterMgr The {@link AdapterManager} to be globally used.
      */
     public static void setAdapterManager(final AdapterManager adapterMgr) {
         ADAPTER_MANAGER = adapterMgr;
     }
 
     /**
-     * Unset an adapter manager previously set with
-     * {@link #setAdapterManager(AdapterManager)}. If this method is called with
-     * an <code>AdapterManager</code> different from the currently set one it
-     * has no effect.
+     * Unsets the global {@link AdapterManager}.
+     * <p>
+     * This method is intended to only be called by the {@link AdapterManager}
+     * wanting to unregister itself. Currently only a single adapter manager is
+     * supported by this class.
      *
-     * @param adapterMgr The adapter manager
+     * @param adapterMgr The {@link AdapterManager} to be unset. If this is not
+     *            the same as currently registered this method has no effect.
      */
     public static void unsetAdapterManager(final AdapterManager adapterMgr) {
         if (ADAPTER_MANAGER == adapterMgr) {
@@ -64,11 +66,31 @@ public abstract class SlingAdaptable imp
         }
     }
 
-    /** Cache */
+    /**
+     * Cached adapters per type.
+     * <p>
+     * This map is created on demand by the {@link #adaptTo(Class)} method as a
+     * regular <code>HashMap</code>. This means, that extensions of this class
+     * are intended to be short-lived to not hold on to objects and classes for
+     * too long.
+     */
     private Map<Class<?>, Object> adaptersCache;
 
     /**
-     * @see org.apache.sling.api.adapter.Adaptable#adaptTo(java.lang.Class)
+     * Calls into the registered {@link AdapterManager} to adapt this object to
+     * the desired <code>type</code>.
+     * <p>
+     * This method implements a cache of adapters to improve performance. That
+     * is repeated calls to this method with the same class will result in the
+     * same object to be returned.
+     *
+     * @param <AdapterType> The generic type to which this resource is adapted
+     *            to
+     * @param type The Class object of the target type, such as
+     *            <code>javax.jcr.Node.class</code> or
+     *            <code>java.io.File.class</code>
+     * @return The adapter target or <code>null</code> if the resource cannot
+     *         adapt to the requested type
      */
     @SuppressWarnings("unchecked")
     public <AdapterType> AdapterType adaptTo(Class<AdapterType> type) {



Mime
View raw message