| /* |
| * 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 javax.annotation.CheckForNull; |
| import javax.annotation.Nonnull; |
| import javax.servlet.http.HttpServletRequest; |
| |
| import org.osgi.annotation.versioning.ConsumerType; |
| |
| /** |
| * API for providers of resources. Used by the {@link ResourceResolver} to |
| * 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. A resource |
| * provider can either directly implement this service interface, e.g. |
| * when no user authentication is provided (like for bundle resources) |
| * or a {@link ResourceProviderFactory} service can be implemented which |
| * upon successful authentication returns a resource provider with the |
| * given user credentials. |
| * |
| * @deprecated Use the {@link org.apache.sling.spi.resource.provider.ResourceProvider} |
| */ |
| @ConsumerType |
| @Deprecated |
| public interface ResourceProvider { |
| |
| /** |
| * The service name to use when registering implementations of this |
| * interface as services (value is |
| * "org.apache.sling.api.resource.ResourceProvider"). |
| */ |
| String SERVICE_NAME = ResourceProvider.class.getName(); |
| |
| /** |
| * The name of the service registration property containing the root paths |
| * of the resources provided by this provider (value is "provider.roots"). |
| */ |
| String ROOTS = "provider.roots"; |
| |
| /** |
| * The name of the service registration property containing the a boolean |
| * flag whether this provider owns the tree registered by the roots. The |
| * default for this value is {@code false}. If a provider owns a root |
| * no other providers are asked for resources under this root if this |
| * provider does not have a resource. (value is "provider.ownsRoots"). |
| * |
| * @since 2.2 (Sling API Bundle 2.2.0) |
| */ |
| String OWNS_ROOTS = "provider.ownsRoots"; |
| |
| /** |
| * The name of the service registration property containing the a boolean |
| * flag indicating if the ResourceAccessSecurity service should be used for |
| * this provider or not. ResourceProvider implementations are encouraged |
| * to use the ResourceAccessSecurity service for access control unless |
| * the underlying storage already provides it. |
| * The default for this value is {@code false}. |
| * (value is "provider.useResourceAccessSecurity") |
| * @since 2.4 (Sling API Bundle 2.5.0) |
| */ |
| String USE_RESOURCE_ACCESS_SECURITY = "provider.useResourceAccessSecurity"; |
| |
| /** |
| * 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} if |
| * 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 parameterize the resource resolution. An |
| * example of such parameterization is support for a JSR-311 |
| * style resource provider to support the parameterized URL patterns. |
| * |
| * @param resourceResolver |
| * The {@link ResourceResolver} to which the returned |
| * {@link Resource} is attached. |
| * @param request The request |
| * @param path The resource path |
| * @return {@code null} 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} instance. |
| * @deprecated since 2.2.0 (and JCR Resource 2.1.0), this method will not be invoked. |
| */ |
| @Deprecated |
| @CheckForNull Resource getResource(@Nonnull ResourceResolver resourceResolver, @Nonnull HttpServletRequest request, @Nonnull String path); |
| |
| /** |
| * Returns a resource from this resource provider or {@code null} if |
| * the resource provider cannot find it. The path should have one of the {@link #ROOTS} |
| * strings as its prefix. |
| * |
| * The resource provider must not return cached instances for a resource as |
| * the resource resolver will update the resource metadata of the resource |
| * at the end of the resolution process and this metadata might be different |
| * depending on the full path of resource resolution passed into the |
| * resource resolver. |
| * |
| * @param resourceResolver |
| * The {@link ResourceResolver} to which the returned {@link Resource} is attached. |
| * @param path The full path of the resource. |
| * @return {@code null} 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} instance. |
| */ |
| @CheckForNull Resource getResource(@Nonnull ResourceResolver resourceResolver, @Nonnull String path); |
| |
| /** |
| * Returns an {@code Iterator} of {@link Resource} objects loaded from |
| * the children of the given {@code Resource}. The returned {@link Resource} instances |
| * are attached to the same |
| * {@link ResourceResolver} as the given {@code parent} 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. |
| * <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}. |
| * |
| * As with {@link #getResource(ResourceResolver, String)} the returned Resource objects must |
| * not be cached objects. |
| * |
| * @param parent |
| * The {@link Resource Resource} whose children are requested. |
| * @return An {@code Iterator} of {@link Resource} objects or {@code null} if the resource |
| * provider has no children for the given resource. |
| * @throws NullPointerException |
| * If {@code parent} is {@code null}. |
| * @throws org.apache.sling.api.SlingException |
| * If any error occurs acquiring the child resource iterator. |
| */ |
| @CheckForNull Iterator<Resource> listChildren(@Nonnull Resource parent); |
| } |