Package org.apache.sling.api.resource

# Interface ResourceResolverFactory

@ProviderType public interface ResourceResolverFactory
The `ResourceResolverFactory` defines the service API to get and create `ResourceResolver`s.

As soon as the resource resolver is not used anymore, `ResourceResolver.close()` should be called.

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)

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`NEW_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.
`static final String`
`PASSWORD`
Name of the authentication information property providing the password of the user for which to create a resource resolver.
`static final String`
`SUBSERVICE`
Name of the authentication information property providing the Subservice Name for the service requesting a resource resolver.
`static final String`
`USER`
Name of the authentication information property providing the name of the user for which the `getResourceResolver(Map)` method creates resource resolvers.
`static final String`
`USER_IMPERSONATION`
Name of the authentication information property causing the `getResourceResolver(Map)`, `getAdministrativeResourceResolver(Map)`, and `getServiceResourceResolver(Map)` methods to try to impersonate the created resource resolver to the requested user and return the impersonated resource resolver.

## Method Summary

Modifier and Type
Method
Description
`@NotNull ResourceResolver`
`getAdministrativeResourceResolver(Map<String,Object> authenticationInfo)`
Deprecated.
as of 2.4 (bundle version 2.5.0) because of inherent security issues.
`@NotNull ResourceResolver`
`getResourceResolver(Map<String,Object> authenticationInfo)`
Returns a new `ResourceResolver` instance with further configuration taken from the given `authenticationInfo` map.
`@NotNull List<String>`
`getSearchPath()`
Returns the search path used by the resource resolvers to search for resources by relative path.
`@NotNull ResourceResolver`
`getServiceResourceResolver(Map<String,Object> authenticationInfo)`
Returns a new `ResourceResolver` instance with privileges assigned to the service provided by the calling bundle.
`@Nullable ResourceResolver`
`getThreadResourceResolver()`
Returns the `ResourceResolver` for the current thread.

## Field Details

### USER

static final String USER
Name of the authentication information property providing the name of the user for which the `getResourceResolver(Map)` method creates resource resolvers. This property may be missing in which case an anonymous (unauthenticated) resource resolver is returned if possible.

The type of this property, if present, is `String`.

See Also:
  - Constant Field Values

### PASSWORD

static final String PASSWORD
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.

The type of this property, if present, is `char[]`.

See Also:
  - Constant Field Values

### NEW_PASSWORD

static final String NEW_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.

The type of this property, if present, is `String`.

Since:
  2.7 (Sling API Bundle 2.9.0)
See Also:
  - Constant Field Values

### USER_IMPERSONATION

static final String USER_IMPERSONATION
Name of the authentication information property causing the `getResourceResolver(Map)`, `getAdministrativeResourceResolver(Map)`, and `getServiceResourceResolver(Map)` methods to try to impersonate the created resource resolver to the requested user and return the impersonated resource resolver.

If this impersonation fails the actual creation of the resource resolver fails and a `LoginException` is thrown.

If this property is not set in the authentication info or is set to the same name as the `user.name` property this property is ignored.

The type of this property, if present, is `String`.

See Also:
  - Constant Field Values

### SUBSERVICE

static final String SUBSERVICE
Name of the authentication information property providing the Subservice Name for the service requesting a resource resolver.

The type of this property, if present, is `String`.

Since:
  2.4 (Sling API Bundle 2.5.0)
See Also:
  - `getServiceResourceResolver(Map)`
  - Constant Field Values

## Method Details

### getResourceResolver

@NotNull @NotNull ResourceResolver getResourceResolver(Map<String,Object> authenticationInfo) throws LoginException
Returns a new `ResourceResolver` instance with further configuration taken from the given `authenticationInfo` map. Generally this map will contain a user name and password to authenticate.

If the `authenticationInfo` map is `null` the `ResourceResolver` returned will generally not be authenticated and only provide minimal privileges, if any at all.

The `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 `LoginException` is thrown.

Parameters:
  `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 `null`.
Returns:
  A `ResourceResolver` according to the `authenticationInfo`.
Throws:
  `LoginException` - If an error occurs creating the new `ResourceResolver` with the provided credential data.

### getAdministrativeResourceResolver

@Deprecated @NotNull @NotNull ResourceResolver getAdministrativeResourceResolver(Map<String,Object> authenticationInfo) throws LoginException
Deprecated.
as of 2.4 (bundle version 2.5.0) because of inherent security issues. Services requiring specific permissions should use the `getServiceResourceResolver(Map)` instead.
Returns a new `ResourceResolver` instance with administrative privileges with further configuration taken from the given `authenticationInfo` map.

Note, that if the `authenticationInfo` map contains the `USER_IMPERSONATION` attribute the `ResourceResolver` returned will only have administrative privileges if the user identified by the property has administrative privileges.

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 `getResourceResolver(Map)` must be used.

This method is deprecated. Services running in the Sling system should use the `getServiceResourceResolver(Map)` method instead. Implementations of this method should throw `LoginException` if they don't support it.

Parameters:
  `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 `null`.
Returns:
  A `ResourceResolver` with administrative privileges unless the `USER_IMPERSONATION` was set in the `authenticationInfo`.
Throws:
  `LoginException` - If an error occurs creating the new `ResourceResolver` with the provided credential data.

### getServiceResourceResolver

@NotNull @NotNull ResourceResolver getServiceResourceResolver(Map<String,Object> authenticationInfo) throws LoginException
Returns a new `ResourceResolver` instance with privileges assigned to the service provided by the calling bundle.

The provided `authenticationInfo` map may be used to provide additional information such as the "sling.service.subservice". `USER` and `PASSWORD` properties provided in the map are ignored.

The `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 `LoginException` is thrown.

Parameters:
  `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 `null`.
Returns:
  A `ResourceResolver` with appropriate permissions to execute the service.
Throws:
  `LoginException` - If an error occurs creating the new `ResourceResolver` for the service represented by the calling bundle.
Since:
  2.4 (Sling API Bundle 2.5.0) to replace `getAdministrativeResourceResolver(Map)`
See Also:
  - Service Authentication

### getThreadResourceResolver

@Nullable @Nullable ResourceResolver getThreadResourceResolver()
Returns the `ResourceResolver` for the current thread.

Each resource resolver created by `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.

This will never return a resource resolver being created via `getAdministrativeResourceResolver(Map)` nor via `getServiceResourceResolver(Map)`.

Returns:
  A `ResourceResolver` created from the current thread or `null`.
Since:
  2.6 (Sling API Bundle 2.8.0)

### getSearchPath

@NotNull @NotNull List<String> getSearchPath()
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.

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.

Returns:
  An immutable list containing the search path
Since:
  2.11 (Sling API Bundle 2.18.0)