org.apache.sling.api.resource

Interface ResourceResolverFactory

@ProviderType
public interface ResourceResolverFactory

The ResourceResolverFactory defines the service API to get and create ResourceResolvers.

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 and Description
static java.lang.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 java.lang.String	PASSWORD Name of the authentication information property providing the password of the user for which to create a resource resolver.
static java.lang.String	SUBSERVICE Name of the authentication information property providing the Subservice Name for the service requesting a resource resolver.
static java.lang.String	USER Name of the authentication information property providing the name of the user for which the getResourceResolver(Map) method creates resource resolvers.
static java.lang.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 and Description
@NotNull ResourceResolver	getAdministrativeResourceResolver(java.util.Map<java.lang.String,java.lang.Object> authenticationInfo) 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.
@NotNull ResourceResolver	getResourceResolver(java.util.Map<java.lang.String,java.lang.Object> authenticationInfo) Returns a new ResourceResolver instance with further configuration taken from the given authenticationInfo map.
@NotNull java.util.List<java.lang.String>	getSearchPath() Returns the search path used by the resource resolvers to search for resources by relative path.
@NotNull ResourceResolver	getServiceResourceResolver(java.util.Map<java.lang.String,java.lang.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 Detail

USER

static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 Detail

getResourceResolver

@NotNull
@NotNull ResourceResolver getResourceResolver(java.util.Map<java.lang.String,java.lang.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(java.util.Map<java.lang.String,java.lang.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(java.util.Map<java.lang.String,java.lang.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 java.util.List<java.lang.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)