Author: cziegeler
Date: Tue May 29 12:26:12 2012
New Revision: 1343698
URL: http://svn.apache.org/viewvc?rev=1343698&view=rev
Log:
SLING-2396 : Add new resource provider interfaces (WiP)
Modified:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
Modified:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java?rev=1343698&r1=1343697&r2=1343698&view=diff
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
(original)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
Tue May 29 12:26:12 2012
@@ -21,28 +21,32 @@ package org.apache.sling.api.resource;
import java.util.Collection;
/**
- * @since 2.3
+ * The attributes provider is an extensions of a {@link ResourceProvider}.
+ * It allows to add attributes to the set of available attributes from a
+ * resource resolver.
+ *
+ * @see ResourceResolver#getAttribute(String)
+ * @see ResourceResolver#getAttributeNames()
+ *
+ * @since 2.2
*/
public interface AttributesProvider {
/**
- * Returns an iterator of attribute names whose value can be retrieved
- * calling the {@link #getAttribute(String)} method. This iterator will not
- * include any attributes which are not accessible.
- *
- * @return An iterator of attribute names
- * @throws IllegalStateException
- * if this resource provider has already been
- * closed.
+ * Returns a collection of attribute names whose value can be retrieved
+ * calling the {@link #getAttribute(String)} method.
+ *
+ * @return A collection of attribute names or <code>null</code>
+ * @throws IllegalStateException if this resource provider has already been
+ * closed.
*/
Collection<String> getAttributeNames();
/**
- * Returns the value of the given resource provider attribute or
<code>null</code> if the
- * attribute is not set (or not visible as is the
- * case of the {@link ResourceResolverFactory#PASSWORD} or other security
+ * Returns the value of the given resource provider attribute or
<code>null</code>
+ * if the attribute is not set or not visible (as e.g. security
* sensitive attributes).
- *
+ *
* @param name
* The name of the attribute to access
* @return The value of the attribute or <code>null</code> if the attribute
@@ -50,7 +54,7 @@ public interface AttributesProvider {
* @throws NullPointerException
* if <code>name</code> is <code>null</code>.
* @throws IllegalStateException
- * if this resource resolver has already been closed.
+ * if this resource provider has already been closed.
*/
Object getAttribute(String name);
}
Modified:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java?rev=1343698&r1=1343697&r2=1343698&view=diff
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
(original)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
Tue May 29 12:26:12 2012
@@ -19,22 +19,36 @@
package org.apache.sling.api.resource;
/**
- * @since 2.3
+ * A dynamic resource provider is an extension of a resource provider which
+ * is only supported if the resource provider has been created through
+ * a {@link ResourceProviderFactory}.
+ *
+ * A dynamic resource provider supports access to systems where the
+ * connection to the system is dynamic and might go away (due to network
+ * changes, updates etc.).
+ *
+ * @see ResourceProviderFactory#getResourceProvider(java.util.Map)
+ * @since 2.2
*/
public interface DynamicResourceProvider {
/**
* Returns <code>true</code> if this resource provider has not been closed
- * yet.
+ * yet and can still be used.
* <p>
- * Unlike the other methods defined in this interface, this method will
never throw an exception
- * even after the resource provider.
- *
+ * This method will never throw an exception
+ * even after the resource provider has been closed
+ *
* @return <code>true</code> if the resource provider has not been closed
- * yet. Once the resource provider has been closed, this method
- * returns <code>false</code>.
+ * yet and is still active.. Once the resource provider has been
closed
+ * or is not active anymore, this method returns
<code>false</code>.
*/
boolean isLive();
+ /**
+ * Close the resource provider.
+ * Once the resource provider is not used anymore, it should be closed with
+ * this method.
+ */
void close();
}
Modified:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java?rev=1343698&r1=1343697&r2=1343698&view=diff
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
(original)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
Tue May 29 12:26:12 2012
@@ -23,6 +23,9 @@ import java.util.Map;
/**
+ * A queriable resource provider is an extension of a resource provider.
+ *
+ * @since 2.2.0
*/
public interface QueriableResourceProvider {
@@ -46,8 +49,8 @@ public interface QueriableResourceProvid
* language is not supported.
* @throws org.apache.sling.api.SlingException If an error occurrs querying
* for the resources.
- * @throws IllegalStateException if this resource resolver has already been
- * {@link #close() closed}.
+ * @throws IllegalStateException if this resource provider has already been
+ * closed.
*/
Iterator<Resource> findResources(String query, String language);
@@ -74,8 +77,8 @@ public interface QueriableResourceProvid
* language is not supported.
* @throws org.apache.sling.api.SlingException If an error occurrs querying
* for the resources.
- * @throws IllegalStateException if this resource resolver has already been
- * {@link #close() closed}.
+ * @throws IllegalStateException if this resource provider has already been
+ * closed.
*/
Iterator<Map<String, Object>> queryResources(String query, String
language);
}
Modified:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java?rev=1343698&r1=1343697&r2=1343698&view=diff
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
(original)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
Tue May 29 12:26:12 2012
@@ -26,8 +26,8 @@ import java.util.Map;
* <p>
* If the resource provider is not used anymore and implements the {@link
java.io.Closeable}
* interface, the close method should be called.
- *
- * @since 2.3
+ *
+ * @since 2.2.0
*/
public interface ResourceProviderFactory {
@@ -41,7 +41,7 @@ public interface ResourceProviderFactory
* If the <code>authenticationInfo</code> map is <code>null</code> the
* <code>ResourceResolver</code> returned will generally not be
authenticated and only provide
* minimal privileges, if any at all.
- *
+ *
* @param authenticationInfo
* A map of further credential information which may be used by
* the implementation to parametrize how the resource resolver
is
@@ -68,7 +68,7 @@ public interface ResourceProviderFactory
* repository and provide general services. This method MUST not be used
to handle client
* requests of whatever kinds. To handle client requests a regular
authenticated resource
* resolver retrieved through {@link #getResourceResolver(Map)} must be
used.</i></b>
- *
+ *
* @param authenticationInfo
* A map of further credential information which may be used by
* the implementation to parametrize how the resource resolver
is
