src/main/java/org/apache/sling/api/resource/ResourceResolverFactory.java - sling-org-apache-sling-api - Git at Google

 /*
  * 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.List;
 import java.util.Map;

 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.NotNull;

 import org.osgi.annotation.versioning.ProviderType;

 /**
  * The <code>ResourceResolverFactory</code> defines the service API to get and
  * create <code>ResourceResolver</code>s.
  * <p>
  * As soon as the resource resolver is not used anymore,
  * {@link ResourceResolver#close()} should be called.
  * <p>
  * All resource resolvers returned by the same resource resolver factory
  * must use the same search path
  *
  * @since 2.1 (Sling API Bundle 2.1.0)
  */
 @ProviderType
 public interface ResourceResolverFactory {

     /**
      * Name of the authentication information property providing the name of the
      * user for which the {@link #getResourceResolver(Map)} method creates
      * resource resolvers. This property may be missing in which case an
      * anonymous (unauthenticated) resource resolver is returned if possible.
      * <p>
      * The type of this property, if present, is <code>String</code>.
      */
     String USER = "user.name";

     /**
      * Name of the authentication information property providing the password of
      * the user for which to create a resource resolver. If this property is
      * missing an empty password is assumed.
      * <p>
      * The type of this property, if present, is <code>char[]</code>.
      */
     String PASSWORD = "user.password";

     /**
      * Name of the authentication information property providing the new password of
      * the user for which to create a resource resolver and change the password during login.
      * <p>
      * The type of this property, if present, is <code>String</code>.
      * @since 2.7 (Sling API Bundle 2.9.0)
      */
     String NEW_PASSWORD = "user.newpassword";

     /**
      * Name of the authentication information property causing the
      * {@link #getResourceResolver(Map)},
      * {@link #getAdministrativeResourceResolver(Map)}, and
      * {@link #getServiceResourceResolver(Map)} methods to try to impersonate
      * the created resource resolver to the requested user and return the
      * impersonated resource resolver.
      * <p>
      * If this impersonation fails the actual creation of the resource resolver
      * fails and a {@code LoginException} is thrown.
      * <p>
      * If this property is not set in the authentication info or is set to the
      * same name as the {@link #USER user.name} property this property is
      * ignored.
      * <p>
      * The type of this property, if present, is <code>String</code>.
      */
     String USER_IMPERSONATION = "user.impersonation";

     /**
      * Name of the authentication information property providing the Subservice
      * Name for the service requesting a resource resolver.
      * <p>
      * The type of this property, if present, is <code>String</code>.
      *
      * @see #getServiceResourceResolver(Map)
      * @since 2.4 (Sling API Bundle 2.5.0)
      */
     String SUBSERVICE = "sling.service.subservice";

     /**
      * Returns a new {@link ResourceResolver} 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.
      * <p>
      * The {@link #USER_IMPERSONATION} property is obeyed but requires that the
      * actual user has permission to impersonate as the requested user. If such
      * permission is missing, a {@code LoginException} is thrown.
      *
      * @param authenticationInfo A map of further credential information which
      *            may be used by the implementation to parameterize 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 occurs creating the new
      *             <code>ResourceResolver</code> with the provided credential
      *             data.
      */
     @NotNull ResourceResolver getResourceResolver(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>
      * <p>
      * This method is deprecated. Services running in the Sling system should
      * use the {@link #getServiceResourceResolver(Map)} method instead.
      * Implementations of this method should throw {@code LoginException} if
      * they don't support it.
      *
      * @param authenticationInfo A map of further credential information which
      *            may be used by the implementation to parameterize 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 occurs creating the new
      *             <code>ResourceResolver</code> with the provided credential
      *             data.
      * @deprecated as of 2.4 (bundle version 2.5.0) because of inherent security
      *             issues. Services requiring specific permissions should use
      *             the {@link #getServiceResourceResolver(Map)} instead.
      */
     @Deprecated
     @NotNull ResourceResolver getAdministrativeResourceResolver(Map<String, Object> authenticationInfo) throws LoginException;

     /**
      * Returns a new {@link ResourceResolver} instance with privileges assigned
      * to the service provided by the calling bundle.
      * <p>
      * The provided {@code authenticationInfo} map may be used to provide
      * additional information such as the {@value #SUBSERVICE}.
      * {@link #USER} and {@link #PASSWORD} properties provided in the map are
      * ignored.
      * <p>
      * The {@link #USER_IMPERSONATION} property is obeyed but requires that the
      * actual service user has permission to impersonate as the requested user.
      * If such permission is missing, a {@code LoginException} is thrown.
      *
      * @param authenticationInfo A map of further service information which may
      *            be used by the implementation to parameterize how the resource
      *            resolver is created. This may be <code>null</code>.
      * @return A {@link ResourceResolver} with appropriate permissions to
      *         execute the service.
      * @throws LoginException If an error occurs creating the new
      *             <code>ResourceResolver</code> for the service represented by
      *             the calling bundle.
      * @since 2.4 (Sling API Bundle 2.5.0) to replace
      *        {@link #getAdministrativeResourceResolver(Map)}
      * @see <a
      *      href="http://sling.apache.org/documentation/the-sling-engine/service-authentication.html">Service
      *      Authentication</a>
      */
     @NotNull ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) throws LoginException;

     /**
      * Returns the {@link ResourceResolver} for the current thread.
      * <p>
      * Each resource resolver created by {@link #getResourceResolver(Map)} is associated with
      * the thread of its creation time. From within this thread, this method returns
      * the last non-closed resource resolver. When a resource resolver is closed, the
      * association is removed.
      * <p>
      * This will never return a resource resolver being created via {@link #getAdministrativeResourceResolver(Map)}
      * nor via {@link #getServiceResourceResolver(Map)}.
      *
      * @return A {@link ResourceResolver} created from the current thread or <code>null</code>.
      *
      * @since 2.6 (Sling API Bundle 2.8.0)
      */
     @Nullable ResourceResolver getThreadResourceResolver();

     /**
      * Returns the search path used by the resource resolvers to search for
      * resources by relative path. If no search path is set an empty list
      * is returned.
      * <p>
      * Each entry in the list is an absolute path terminated with a slash
      * character. Thus to create an absolute path from a search path entry and a
      * relative path, the search path entry and relative path may just be
      * concatenated.
      *
      * @return An immutable list containing the search path
      * @since 2.11 (Sling API Bundle 2.18.0)
      */
     @NotNull List<String> getSearchPath();
 }
	/*
	* 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.List;
	import java.util.Map;

	import org.jetbrains.annotations.Nullable;
	import org.jetbrains.annotations.NotNull;

	import org.osgi.annotation.versioning.ProviderType;

	/**
	* The <code>ResourceResolverFactory</code> defines the service API to get and
	* create <code>ResourceResolver</code>s.
	* <p>
	* As soon as the resource resolver is not used anymore,
	* {@link ResourceResolver#close()} should be called.
	* <p>
	* All resource resolvers returned by the same resource resolver factory
	* must use the same search path
	*
	* @since 2.1 (Sling API Bundle 2.1.0)
	*/
	@ProviderType
	public interface ResourceResolverFactory {

	/**
	* Name of the authentication information property providing the name of the
	* user for which the {@link #getResourceResolver(Map)} method creates
	* resource resolvers. This property may be missing in which case an
	* anonymous (unauthenticated) resource resolver is returned if possible.
	* <p>
	* The type of this property, if present, is <code>String</code>.
	*/
	String USER = "user.name";

	/**
	* Name of the authentication information property providing the password of
	* the user for which to create a resource resolver. If this property is
	* missing an empty password is assumed.
	* <p>
	* The type of this property, if present, is <code>char[]</code>.
	*/
	String PASSWORD = "user.password";

	/**
	* Name of the authentication information property providing the new password of
	* the user for which to create a resource resolver and change the password during login.
	* <p>
	* The type of this property, if present, is <code>String</code>.
	* @since 2.7 (Sling API Bundle 2.9.0)
	*/
	String NEW_PASSWORD = "user.newpassword";

	/**
	* Name of the authentication information property causing the
	* {@link #getResourceResolver(Map)},
	* {@link #getAdministrativeResourceResolver(Map)}, and
	* {@link #getServiceResourceResolver(Map)} methods to try to impersonate
	* the created resource resolver to the requested user and return the
	* impersonated resource resolver.
	* <p>
	* If this impersonation fails the actual creation of the resource resolver
	* fails and a {@code LoginException} is thrown.
	* <p>
	* If this property is not set in the authentication info or is set to the
	* same name as the {@link #USER user.name} property this property is
	* ignored.
	* <p>
	* The type of this property, if present, is <code>String</code>.
	*/
	String USER_IMPERSONATION = "user.impersonation";

	/**
	* Name of the authentication information property providing the Subservice
	* Name for the service requesting a resource resolver.
	* <p>
	* The type of this property, if present, is <code>String</code>.
	*
	* @see #getServiceResourceResolver(Map)
	* @since 2.4 (Sling API Bundle 2.5.0)
	*/
	String SUBSERVICE = "sling.service.subservice";

	/**
	* Returns a new {@link ResourceResolver} 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.
	* <p>
	* The {@link #USER_IMPERSONATION} property is obeyed but requires that the
	* actual user has permission to impersonate as the requested user. If such
	* permission is missing, a {@code LoginException} is thrown.
	*
	* @param authenticationInfo A map of further credential information which
	* may be used by the implementation to parameterize 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 occurs creating the new
	* <code>ResourceResolver</code> with the provided credential
	* data.
	*/
	@NotNull ResourceResolver getResourceResolver(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>
	* <p>
	* This method is deprecated. Services running in the Sling system should
	* use the {@link #getServiceResourceResolver(Map)} method instead.
	* Implementations of this method should throw {@code LoginException} if
	* they don't support it.
	*
	* @param authenticationInfo A map of further credential information which
	* may be used by the implementation to parameterize 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 occurs creating the new
	* <code>ResourceResolver</code> with the provided credential
	* data.
	* @deprecated as of 2.4 (bundle version 2.5.0) because of inherent security
	* issues. Services requiring specific permissions should use
	* the {@link #getServiceResourceResolver(Map)} instead.
	*/
	@Deprecated
	@NotNull ResourceResolver getAdministrativeResourceResolver(Map<String, Object> authenticationInfo) throws LoginException;

	/**
	* Returns a new {@link ResourceResolver} instance with privileges assigned
	* to the service provided by the calling bundle.
	* <p>
	* The provided {@code authenticationInfo} map may be used to provide
	* additional information such as the {@value #SUBSERVICE}.
	* {@link #USER} and {@link #PASSWORD} properties provided in the map are
	* ignored.
	* <p>
	* The {@link #USER_IMPERSONATION} property is obeyed but requires that the
	* actual service user has permission to impersonate as the requested user.
	* If such permission is missing, a {@code LoginException} is thrown.
	*
	* @param authenticationInfo A map of further service information which may
	* be used by the implementation to parameterize how the resource
	* resolver is created. This may be <code>null</code>.
	* @return A {@link ResourceResolver} with appropriate permissions to
	* execute the service.
	* @throws LoginException If an error occurs creating the new
	* <code>ResourceResolver</code> for the service represented by
	* the calling bundle.
	* @since 2.4 (Sling API Bundle 2.5.0) to replace
	* {@link #getAdministrativeResourceResolver(Map)}
	* @see <a
	* href="http://sling.apache.org/documentation/the-sling-engine/service-authentication.html">Service
	* Authentication</a>
	*/
	@NotNull ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) throws LoginException;

	/**
	* Returns the {@link ResourceResolver} for the current thread.
	* <p>
	* Each resource resolver created by {@link #getResourceResolver(Map)} is associated with
	* the thread of its creation time. From within this thread, this method returns
	* the last non-closed resource resolver. When a resource resolver is closed, the
	* association is removed.
	* <p>
	* This will never return a resource resolver being created via {@link #getAdministrativeResourceResolver(Map)}
	* nor via {@link #getServiceResourceResolver(Map)}.
	*
	* @return A {@link ResourceResolver} created from the current thread or <code>null</code>.
	*
	* @since 2.6 (Sling API Bundle 2.8.0)
	*/
	@Nullable ResourceResolver getThreadResourceResolver();

	/**
	* Returns the search path used by the resource resolvers to search for
	* resources by relative path. If no search path is set an empty list
	* is returned.
	* <p>
	* Each entry in the list is an absolute path terminated with a slash
	* character. Thus to create an absolute path from a search path entry and a
	* relative path, the search path entry and relative path may just be
	* concatenated.
	*
	* @return An immutable list containing the search path
	* @since 2.11 (Sling API Bundle 2.18.0)
	*/
	@NotNull List<String> getSearchPath();
	}