API Enhancement: Add ResourceResolverFactory

Status: DRAFT
Created: 9. November 2008
Author: fmeschbe

1 Current State

The Sling API currently only defines the ResourceResolver interface but not how such a resolver is to be created/retrieved.

In addition the Sling implementation has:

• Sling Repository providers, which just register one or more repository instances as services
• JcrResourceResolverFactory service which creates ResourceResolver instances based on JCR Session objects
• The authenticator selects one of the Repository services to authenticate against and creates the Session to get the ResourceResolver from the JcrResourceResolverFactory

This implementation has a series of drawbacks:

• The authenticator decides which repository to access: Problem is, that the authenticator is most probably not the right instance to decide on this issue.
• Getting a Resource resolver is tedious in that a Session is first to be created and then a resolver can be retrieved from the factory
• Only a single workspace of a single repository may be accessed at a any time and the authenticator actually defines which of those.
• All in all, this decouples the ResourceResolverProvider too much from the repository and gives the authenticator too much "power"

Therefore I propose the extension of the Sling API as presented herein.

2 Extensions at a Glance

This is the list of additions, I propose for the Sling API. Please refer to then following sections for more details, description and motivation.

• Add ResourceResolverFactory service interface which provides a ResourceResolver instances
• Add ResourceProviderFactory service interface to help ResourceResolverFactory in creating ResourceResolver instances
• Add lifecyle support to the ResourceResolver and ResourceProvider interfaces

3 ResourceResolverFactory

The ResourceResolverFactory is installed into the system as a service. The factory provides a single method

ResourceResolver getResourceResolver(Map<String, Object> credentials) throws LoginException

This method uses the credentials object to authenticate the user and to create ResourceResolver, which may then be used. If authentication fails, a LoginException (extends SlingException) is thrown.

Authentication fails if at least one ResourceProviderFactory service which is registered with the provider.required property set to true throws a LoginExcdeption. This for example allows multiple ResourceProviderFactory services to be registered to access the JCR repository, each for a different location/workspace and one factory service to be the one to decide, whether authentication succeeds or not. ResourceResovlerFactory services not having the provider.required property set to true will just be ignored if they cannot return a ResourceProvider.

4 ResourceResolver

The ResourceResolver API is extended with a new method

void close()

which must be called when the resource resolver is no longer used.

5 ResourceProviderFactory

The ResourceResolverFactory will return a ResourceResolver which behind the scenes makes use of ReosurceProvider instances. This interface already exists today and is implemented to access bundle or filesystem resources. In fact also repository access is internally implemented as a ResourceProvider.

To allow for authenticated ResourceProvider instances in addition to unauthenticated ones, a new factory interface ResourceProviderFactory is introduced which provides a single method:

ResourceProvider getResourceProvider(Map<String, Object> credentials) throws LoginException

This method returns a resource provider with the given credentials or throws a LoginException if the credentials do not allow access to the provider.

The ResourceProviderFactory is a service interface and as such the registered ResourceProviderFactory services have the following defined service registration properties:

• provider.roots - Defines the root paths under which the ResourceProvider is attached into Resource tree. This is the same property as for the ResourceProvider service and applies to all ResourceProvider instances returned by the factory
• provider.required - Indicates whether the ResourceProvider instances provided by the ResourceProviderFactory have to be assumed as required.

6 ResourceProvider

To allow for ResourceProvider instances returned by ResourceProviderFactory services to be closed when no longer used, a new method is added to the ResourceProvider interface:

void close()

This method must close the ResourceProvider. For example a JCR based ResourceProvider will logout the underlying session upon close.

This method will have no effect if called on a ResourceProvider which is registered as a service. For example the BundleResourceProvider will implement an empty close() method.

7 Loging into the System

To log into the system, the authenticator will extract the credentials from the HTTP request and call the ResourceResolverFactory.getResourceResolver method with the credentials. If the ResourceResolverFactory throws a LoginException, authentication failed.