Author: cziegeler
Date: Thu May 24 06:41:46 2012
New Revision: 1342153
URL: http://svn.apache.org/viewvc?rev=1342153&view=rev
Log:
SLING-2396 : Add new resource provider interfaces (WiP)
Added:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
(with props)
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
(with props)
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
(with props)
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
(with props)
Modified:
sling/whiteboard/SLING-2396/api/pom.xml
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProvider.java
Modified: sling/whiteboard/SLING-2396/api/pom.xml
URL:
http://svn.apache.org/viewvc/sling/whiteboard/SLING-2396/api/pom.xml?rev=1342153&r1=1342152&r2=1342153&view=diff
==============================================================================
--- sling/whiteboard/SLING-2396/api/pom.xml (original)
+++ sling/whiteboard/SLING-2396/api/pom.xml Thu May 24 06:41:46 2012
@@ -28,7 +28,7 @@
</parent>
<artifactId>org.apache.sling.api</artifactId>
- <version>2.2.5-SNAPSHOT</version>
+ <version>2.2.5-WHITEBOARD-SNAPSHOT</version>
<packaging>bundle</packaging>
<name>Apache Sling API</name>
Added:
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=1342153&view=auto
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
(added)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
Thu May 24 06:41:46 2012
@@ -0,0 +1,56 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.sling.api.resource;
+
+import java.util.Collection;
+
+/**
+ * @since 2.3
+ */
+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.
+ */
+ 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
+ * sensitive attributes).
+ *
+ * @param name
+ * The name of the attribute to access
+ * @return The value of the attribute or <code>null</code> if the attribute
+ * is not set or not accessible.
+ * @throws NullPointerException
+ * if <code>name</code> is <code>null</code>.
+ * @throws IllegalStateException
+ * if this resource resolver has already been closed.
+ */
+ Object getAttribute(String name);
+}
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
------------------------------------------------------------------------------
svn:keywords = author date id revision rev url
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/AttributesProvider.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
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=1342153&view=auto
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
(added)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
Thu May 24 06:41:46 2012
@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.sling.api.resource;
+
+/**
+ * @since 2.3
+ */
+public interface DynamicResourceProvider {
+
+ /**
+ * Returns <code>true</code> if this resource provider has not been closed
+ * yet.
+ * <p>
+ * Unlike the other methods defined in this interface, this method will
never throw an exception
+ * even after the resource provider.
+ *
+ * @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>.
+ */
+ boolean isLive();
+
+ void close();
+}
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
------------------------------------------------------------------------------
svn:keywords = author date id revision rev url
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/DynamicResourceProvider.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added:
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=1342153&view=auto
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
(added)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
Thu May 24 06:41:46 2012
@@ -0,0 +1,81 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.sling.api.resource;
+
+import java.util.Iterator;
+import java.util.Map;
+
+
+/**
+ */
+public interface QueriableResourceProvider {
+
+ /**
+ * Searches for resources using the given query formulated in the given
+ * language.
+ * <p>
+ * The semantic meaning of the query and language depend on the actual
+ * implementation and storage used for the resources. For JCR repository
+ * being used as storage, the query and lanuage parameters are used to
+ * create a JCR <code>Query</code> through the <code>QueryManager</code>.
+ * The result returned is then based on the <code>NodeIterator</code>
+ * provided by the query result.
+ *
+ * @param query The query string to use to find the resources.
+ * @param language The language in which the query is formulated.
+ * @return An <code>Iterator</code> of {@link Resource} objects matching
the
+ * query.
+ * @throws QuerySyntaxException If the query is not syntactically correct
+ * according to the query language indicator of if the query
+ * 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}.
+ */
+ Iterator<Resource> findResources(String query, String language);
+
+ /**
+ * Queries the storage using the given query formulated in the given
+ * language.
+ * <p>
+ * The semantic meaning of the query and language depend on the actual
+ * implementation and storage used for the resources. For JCR repository
+ * being used as storage, the query and lanuage parameters are used to
+ * create a JCR <code>Query</code> through the <code>QueryManager</code>.
+ * The result returned is then based on the <code>RowIterator</code>
+ * provided by the query result. The map returned for each row is indexed
by
+ * the column name and the column value is the JCR <code>Value</code>
object
+ * converted into the respective Java object, such as <code>Boolean</code>
+ * for a value of property type <em>Boolean</em>.
+ *
+ * @param query The query string to use to find the resources.
+ * @param language The language in which the query is formulated.
+ * @return An <code>Iterator</code> of <code>Map</code> instances providing
+ * access to the query result.
+ * @throws QuerySyntaxException If the query is not syntactically correct
+ * according to the query language indicator of if the query
+ * 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}.
+ */
+ Iterator<Map<String, Object>> queryResources(String query, String
language);
+}
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
------------------------------------------------------------------------------
svn:keywords = author date id revision rev url
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/QueriableResourceProvider.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProvider.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProvider.java?rev=1342153&r1=1342152&r2=1342153&view=diff
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProvider.java
(original)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProvider.java
Thu May 24 06:41:46 2012
@@ -29,9 +29,8 @@ import org.apache.sling.api.SlingExcepti
* transparently access resources from different locations such as a JCR
* repository (the default) or OSGi bundles.
* <p>
- * This interface is intended to be implemented by providers of Resource
- * instances on behalf of the {@link ResourceResolver}. It is not intended to
- * be used by client applications directly.
+ * This interface is intended to be implemented by providers of Resource
instances on behalf of the {@link ResourceResolver}. It
+ * is not intended to be used by client applications directly.
*/
public interface ResourceProvider {
@@ -49,75 +48,67 @@ public interface ResourceProvider {
String ROOTS = "provider.roots";
/**
- * The resource type be set on resources returned by the
- * {@link #listChildren(Resource)} method to enable traversing the resource
+ * The resource type be set on resources returned by the {@link
#listChildren(Resource)} method to enable traversing the
+ * resource
* tree down to a deeply nested provided resource which has no concrete
* parent hierarchy (value is"sling:syntheticResourceProviderResource").
- *
+ *
* @see #listChildren(Resource)
*/
String RESOURCE_TYPE_SYNTHETIC = "sling:syntheticResourceProviderResource";
/**
* Returns a resource from this resource provider or <code>null</code> if
- * the resource provider cannot find it. The path should have one of the
- * {@link #ROOTS} strings as its prefix.
+ * the resource provider cannot find it. The path should have one of the
{@link #ROOTS} strings as its prefix.
* <p>
- * This method is called to resolve a resource for the given request. The
- * properties of the request, such as request parameters, may be use to
- * parametrize the resource resolution. An example of such parametrization
- * is support for a JSR-311 style resource provider to support the
- * parametrized URL patterns.
- *
- * @param resourceResolver The {@link ResourceResolver} to which the
- * returned {@link Resource} is attached.
+ * This method is called to resolve a resource for the given request. The
properties of the request, such as request
+ * parameters, may be use to parametrize the resource resolution. An
example of such parametrization is support for a JSR-311
+ * style resource provider to support the parametrized URL patterns.
+ *
+ * @param resourceResolver
+ * The {@link ResourceResolver} to which the returned {@link
Resource} is attached.
* @return <code>null</code> If this provider does not have a resource for
* the path.
- * @throws org.apache.sling.api.SlingException may be thrown in case of
any problem creating the
- * <code>Resource</code> instance.
+ * @throws org.apache.sling.api.SlingException
+ * may be thrown in case of any problem creating the
<code>Resource</code> instance.
*/
- Resource getResource(ResourceResolver resourceResolver,
- HttpServletRequest request, String path);
+ Resource getResource(ResourceResolver resourceResolver, HttpServletRequest
request, String path);
/**
* Returns a resource from this resource provider or <code>null</code> if
- * the resource provider cannot find it. The path should have one of the
- * {@link #ROOTS} strings as its prefix.
- *
- * @param resourceResolver The {@link ResourceResolver} to which the
- * returned {@link Resource} is attached.
+ * the resource provider cannot find it. The path should have one of the
{@link #ROOTS} strings as its prefix.
+ *
+ * @param resourceResolver
+ * The {@link ResourceResolver} to which the returned {@link
Resource} is attached.
* @return <code>null</code> If this provider does not have a resource for
* the path.
- * @throws org.apache.sling.api.SlingException may be thrown in case of
any problem creating the
- * <code>Resource</code> instance.
+ * @throws org.apache.sling.api.SlingException
+ * may be thrown in case of any problem creating the
<code>Resource</code> instance.
*/
Resource getResource(ResourceResolver resourceResolver, String path);
/**
- * Returns an <code>Iterator</code> of {@link Resource} objects loaded
- * from the children of the given <code>Resource</code>. The returned
- * {@link Resource} instances are attached to the same
+ * Returns an <code>Iterator</code> of {@link Resource} objects loaded from
+ * the children of the given <code>Resource</code>. The returned {@link
Resource} instances are attached to the same
* {@link ResourceResolver} as the given <code>parent</code> resource.
* <p>
- * This method may be called for resource providers whose root path list
- * contains a path such that the resource path is a prefix of the list
- * entry. This allows for the enumeration of deeply nested provided
- * resources for which no actual parent hierarchy exists.
+ * This method may be called for resource providers whose root path list
contains a path such that the resource path is a
+ * prefix of the list entry. This allows for the enumeration of deeply
nested provided resources for which no actual parent
+ * hierarchy exists.
* <p>
- * The returned iterator may in turn contain resources which do not
actually
- * exist but are required to traverse the resource tree. Such resources
- * SHOULD be {@link SyntheticResource} objects whose resource type MUST be
- * set to {@link #RESOURCE_TYPE_SYNTHETIC}.
- *
- * @param parent The {@link Resource Resource} whose children are
requested.
- * @return An <code>Iterator</code> of {@link Resource} objects or
- * <code>null</code> if the resource provider has no children for
+ * The returned iterator may in turn contain resources which do not
actually exist but are required to traverse the resource
+ * tree. Such resources SHOULD be {@link SyntheticResource} objects whose
resource type MUST be set to
+ * {@link #RESOURCE_TYPE_SYNTHETIC}.
+ *
+ * @param parent
+ * The {@link Resource Resource} whose children are requested.
+ * @return An <code>Iterator</code> of {@link Resource} objects or
<code>null</code> if the resource provider has no children
+ * for
* the given resource.
- * @throws NullPointerException If <code>parent</code> is
- * <code>null</code>.
- * @throws SlingException If any error occurs acquiring the child resource
- * iterator.
+ * @throws NullPointerException
+ * If <code>parent</code> is <code>null</code>.
+ * @throws SlingException
+ * If any error occurs acquiring the child resource iterator.
*/
Iterator<Resource> listChildren(Resource parent);
-
}
Added:
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=1342153&view=auto
==============================================================================
---
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
(added)
+++
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
Thu May 24 06:41:46 2012
@@ -0,0 +1,84 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.sling.api.resource;
+
+import java.util.Map;
+
+/**
+ * The <code>ResourceProviderFactory</code> defines the service API to get and
+ * create <code>ResourceProviders</code>s.
+ * <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
+ */
+public interface ResourceProviderFactory {
+
+ String PROPERTY_REQUIRED = "required";
+
+ /**
+ * Returns a new {@link ResourceProvider} instance with further
+ * configuration taken from the given <code>authenticationInfo</code> map.
+ * Generally this map will contain a user name and password to
authenticate.
+ * <p>
+ * 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
+ * created. This may be <code>null</code>.
+ * @return A {@link ResourceResolver} according to the
<code>authenticationInfo</code>.
+ * @throws LoginException
+ * If an error occurrs creating the new
<code>ResourceResolver</code> with the
+ * provided credential
+ * data.
+ */
+ ResourceProvider getResourceProvider(Map<String, Object>
authenticationInfo) throws LoginException;
+
+ /**
+ * Returns a new {@link ResourceResolver} instance with administrative
+ * privileges with further configuration taken from the given
<code>authenticationInfo</code>
+ * map.
+ * <p>
+ * Note, that if the <code>authenticationInfo</code> map contains the
+ * {@link #USER_IMPERSONATION} attribute the <code>ResourceResolver</code>
returned will only
+ * have administrative privileges if the user identified by the property
has administrative
+ * privileges.
+ * <p>
+ * <b><i>NOTE: This method is intended for use by infrastructure bundles
to access the
+ * 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
+ * created. This may be <code>null</code>.
+ * @return A {@link ResourceResolver} with administrative privileges unless
+ * the {@link #USER_IMPERSONATION} was set in the
<code>authenticationInfo</code>.
+ * @throws LoginException
+ * If an error occurrs creating the new
<code>ResourceResolver</code> with the
+ * provided credential
+ * data.
+ */
+ ResourceProvider getAdministrativeResourceProvider(Map<String, Object>
authenticationInfo) throws LoginException;
+}
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
------------------------------------------------------------------------------
svn:keywords = author date id revision rev url
Propchange:
sling/whiteboard/SLING-2396/api/src/main/java/org/apache/sling/api/resource/ResourceProviderFactory.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
