org.apache.sling.spi.resource.provider

Class ResourceProvider<T>

java.lang.Object

org.apache.sling.spi.resource.provider.ResourceProvider<T>

public abstract class ResourceProvider<T>
extends java.lang.Object

API for providers of resources. Used by the ResourceResolver to transparently access resources from different locations such as a JCR repository, a database, or bundle resources.

This extension point is defined by an abstract class (in contrast to an interface) as this allows to add new functionality in new versions without breaking any implementation.

This service is intended to be implemented by providers of resource instances on behalf of the ResourceResolver. It is not intended to be used by client applications directly. A resource provider implements this service by extending this class.

A resource provider must set the PROPERTY_ROOT property with an absolute path. This is the mount point of the resource provider. If there is more than one provider registering for the same root, only the one with the highest service ranking is used.

If a provider is used in the resource tree, it gets activated through a call of the start(ProviderContext) method. If the provider is not used anymore within the resource tree, the stop() method is called. Whenever information concerning the provider is changed while the provider is used, the update(long) method is called. The provider context instance which is passed to the start(ProviderContext) method contains the updated state.

Some resource providers might require (user) authentication. For example the JCR resource provider uses authenticated sessions. If a provider requires authentication it must indicate this by setting the service registration property PROPERTY_AUTHENTICATE to either AUTHENTICATE_LAZY or AUTHENTICATE_REQUIRED. In these cases, the resource resolver calls authenticate(Map) and on successful authentication the provider returns a state object for the current user. This object is passed into the provider with every method through ResolveContext.getProviderState(). If a provider requires authentication, the logout(Object) method is called, when the resource resolver is closed. If the provider does not set this service property or sets it to AUTHENTICATE_NO the authenticate(Map) and logout(Object) method are never called and therefore ResolveContext.getProviderState() will return null.

Each method gets the ResourceContext which gives access to further functionality.

Since:

1.0.0 (Sling API Bundle 2.11.0)

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	AUTH_ADMIN The authentication information property indicating to use an administrative login.
static java.lang.String	AUTH_CLONE The authentication information property indicating that an existing resource resolver is being cloned.
static java.lang.String	AUTH_SERVICE_BUNDLE The authentication information property referring to the bundle providing a service for which a resource provider is to be retrieved.
static java.lang.String	AUTHENTICATE_LAZY Value for PROPERTY_AUTHENTICATE indicating authentication is needed and will be done on demand.
static java.lang.String	AUTHENTICATE_NO Default value for PROPERTY_AUTHENTICATE
static java.lang.String	AUTHENTICATE_REQUIRED Value for PROPERTY_AUTHENTICATE indicating authentication is required.
static java.lang.String	PROPERTY_ADAPTABLE If this flag is set to true, the resource resolver will use this provider for the adaptTo() operation.
static java.lang.String	PROPERTY_ATTRIBUTABLE If this flag is set to true, the resource resolver will try to get the attribute names and the attribute values from this provider.
static java.lang.String	PROPERTY_AUTHENTICATE If a resource provider needs the user to be authenticated this property must be set to either AUTHENTICATE_LAZY or AUTHENTICATE_REQUIRED.
static java.lang.String	PROPERTY_MODIFIABLE A modifiable resource provider is capable of creating, changing and deleting resources.
static java.lang.String	PROPERTY_NAME Optional service registration property setting a name for the provider.
static java.lang.String	PROPERTY_REFRESHABLE If this flag is set to true, the resource resolver will call refresh(ResolveContext) when it's refreshed itself.
static java.lang.String	PROPERTY_ROOT The name of the service registration property containing the root path of the resources provided by this provider.
static java.lang.String	PROPERTY_USE_RESOURCE_ACCESS_SECURITY The name of the service registration property containing a boolean flag indicating if the ResourceAccessSecurity service should be used for this provider or not.
static java.lang.String	RESOURCE_TYPE_SYNTHETIC The resource type be set on resources returned by the listChildren(ResolveContext, 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").

Constructor Summary

Constructors

Constructor and Description
ResourceProvider()

Method Summary

Modifier and Type	Method and Description
<AdapterType> AdapterType	adaptTo(ResolveContext<T> ctx, java.lang.Class<AdapterType> type) Adapts the provider to another type.
T	authenticate(java.util.Map<java.lang.String,java.lang.Object> authenticationInfo) Authenticate against the resource provider.
void	commit(ResolveContext<T> ctx) Commit all transient changes: create, delete and updates
boolean	copy(ResolveContext<T> ctx, java.lang.String srcAbsPath, java.lang.String destAbsPath) This method copies the subgraph rooted at, and including, the resource at srcAbsPath to the new location at destAbsPath and adds it as a child node of the resource at destAbsPath.
Resource	create(ResolveContext<T> ctx, java.lang.String path, java.util.Map<java.lang.String,java.lang.Object> properties) Create a new resource at the given path.
void	delete(ResolveContext<T> ctx, Resource resource) Delete the resource at the given path.
java.lang.Object	getAttribute(ResolveContext<T> ctx, java.lang.String name) Returns the value of the given resource provider attribute or null if the attribute is not set or not visible (as e.g.
java.util.Collection<java.lang.String>	getAttributeNames(ResolveContext<T> ctx) Returns a collection of attribute names whose value can be retrieved calling the getAttribute(ResolveContext, String) method.
Resource	getParent(ResolveContext<T> ctx, Resource child) Returns the parent resource from this resource provider or null if the resource provider cannot find it.
QueryLanguageProvider<T>	getQueryLanguageProvider() Get the optional query language provider.
abstract Resource	getResource(ResolveContext<T> ctx, java.lang.String path, ResourceContext resourceContext, Resource parent) Returns a resource from this resource provider or null if the resource provider cannot find it.
boolean	hasChanges(ResolveContext<T> ctx) Are there any transient changes?
boolean	isLive(ResolveContext<T> ctx) Returns true if this resource provider has not been closed yet and can still be used.
abstract java.util.Iterator<Resource>	listChildren(ResolveContext<T> ctx, Resource parent) Returns an Iterator of Resource objects loaded from the children of the given Resource.
void	logout(T state) If the provider requires authentication, this method is called with the state of the user returned by authenticate(Map) once the resource resolver is closed.
boolean	move(ResolveContext<T> ctx, java.lang.String srcAbsPath, java.lang.String destAbsPath) This method moves the subgraph rooted at, and including, the resource at srcAbsPath to the new location at destAbsPath and adds it as a child node of the resource at destAbsPath.
void	refresh(ResolveContext<T> ctx) The provider is updated to reflect the latest state.
void	revert(ResolveContext<T> ctx) Revert all transient changes: create, delete and updates.
void	start(ProviderContext ctx) With a call to this method, the provider implementation is notified that it is used in the resource tree.
void	stop() With a call to this method, the provider implementation is notified that it is not used anymore in the resource tree.
void	update(long changeSet) With a call to this method, the provider implementation is notified that any information regarding the registration of the provider has changed.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_ROOT

public static final java.lang.String PROPERTY_ROOT

The name of the service registration property containing the root path of the resources provided by this provider. If this property is missing, empty or invalid, the provider is ignored. (value is "provider.root")

See Also:

Constant Field Values

PROPERTY_NAME

public static final java.lang.String PROPERTY_NAME

Optional service registration property setting a name for the provider. The name must not be unique. The name in combination with the root can be used to identify a resource provider.

See Also:

Constant Field Values

PROPERTY_USE_RESOURCE_ACCESS_SECURITY

public static final java.lang.String PROPERTY_USE_RESOURCE_ACCESS_SECURITY

The name of the service registration property containing a boolean flag indicating if the ResourceAccessSecurity service should be used for this provider or not. ResourceAccessSecurity should only be used if the underlying storage does not provide access control The default for this value is false. (value is "provider.useResourceAccessSecurity")

See Also:

Constant Field Values

AUTHENTICATE_NO

public static final java.lang.String AUTHENTICATE_NO

Default value for PROPERTY_AUTHENTICATE

See Also:

PROPERTY_AUTHENTICATE, Constant Field Values

AUTHENTICATE_REQUIRED

public static final java.lang.String AUTHENTICATE_REQUIRED

Value for PROPERTY_AUTHENTICATE indicating authentication is required.

See Also:

PROPERTY_AUTHENTICATE, Constant Field Values

AUTHENTICATE_LAZY

public static final java.lang.String AUTHENTICATE_LAZY

Value for PROPERTY_AUTHENTICATE indicating authentication is needed and will be done on demand.

See Also:

PROPERTY_AUTHENTICATE, Constant Field Values

PROPERTY_AUTHENTICATE

public static final java.lang.String PROPERTY_AUTHENTICATE

If a resource provider needs the user to be authenticated this property must be set to either AUTHENTICATE_LAZY or AUTHENTICATE_REQUIRED. If it is set to AUTHENTICATE_REQUIRED, the authenticate(Map) method is called when the resource resolver is created and only if authentication against all resource providers marked as required is successful, a resource resolver is created. Otherwise the creation fails. If a provider sets this property to AUTHENTICATE_LAZY, the authenticate method is only invoked if a resource from this provider is requested. This might also happen for traversal or queries. If the authentication fails, resources from this provider are not accessible. If this property is not set or set to AUTHENTICATE_NO, no authentication is required for this provider and the authenticate(Map) is never invoked. String service property, default value is AUTHENTICATE_NO. (value is "provider.authenticate")

See Also:

Constant Field Values

PROPERTY_MODIFIABLE

public static final java.lang.String PROPERTY_MODIFIABLE

A modifiable resource provider is capable of creating, changing and deleting resources. This means the methods create(ResolveContext, String, Map), delete(ResolveContext, Resource) and adapting a resource to a modifiable value map is supported. If this flag is set to false, the resource resolver does not take this provider into account for modifications and modification operations to this provider always result in an exception. If this is set to true, the property PROPERTY_AUTHENTICATE must require authentication, otherwise this provider registration is considered invalid and the provider is not used. Boolean service property, default value is false. (value is "provider.modifiable")

See Also:

Constant Field Values

PROPERTY_ADAPTABLE

public static final java.lang.String PROPERTY_ADAPTABLE

If this flag is set to true, the resource resolver will use this provider for the adaptTo() operation. Boolean service property, default value is false. (value is "provider.adaptable")

See Also:

Constant Field Values

PROPERTY_REFRESHABLE

public static final java.lang.String PROPERTY_REFRESHABLE

If this flag is set to true, the resource resolver will call refresh(ResolveContext) when it's refreshed itself. Boolean service property, default value is false. (value is "provider.refreshable")

See Also:

Constant Field Values

PROPERTY_ATTRIBUTABLE

public static final java.lang.String PROPERTY_ATTRIBUTABLE

If this flag is set to true, the resource resolver will try to get the attribute names and the attribute values from this provider. Boolean service property, default value is false. (value is "provider.attributable")

See Also:

Constant Field Values

AUTH_SERVICE_BUNDLE

public static final java.lang.String AUTH_SERVICE_BUNDLE

The authentication information property referring to the bundle providing a service for which a resource provider is to be retrieved. If this property is provided, the ResourceResolverFactory.SUBSERVICE property may also be present.

ResourceResolverFactory implementations must provide this property if their implementation of the ResourceResolverFactory.getServiceResourceResolver(Map) method use a resource provider factory.

The type of this property, if present, is org.osgi.framework.Bundle.

See Also:

Constant Field Values

AUTH_ADMIN

public static final java.lang.String AUTH_ADMIN

The authentication information property indicating to use an administrative login. This property must be set if the resource resolver is created through ResourceResolverFactory.getAdministrativeResourceResolver(Map).

See Also:

Constant Field Values

AUTH_CLONE

public static final java.lang.String AUTH_CLONE

The authentication information property indicating that an existing resource resolver is being cloned. Providers that receive stateful objects as authentication information must deep-clone those objects when this property is present, to avoid inadvertent state sharing with the existing resolver.

Since:

1.2.0

See Also:

Constant Field Values

RESOURCE_TYPE_SYNTHETIC

public static final java.lang.String RESOURCE_TYPE_SYNTHETIC

The resource type be set on resources returned by the listChildren(ResolveContext, 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 Also:

listChildren(ResolveContext, Resource), Constant Field Values

Constructor Detail

ResourceProvider

public ResourceProvider()

Method Detail

start

public void start(ProviderContext ctx)

With a call to this method, the provider implementation is notified that it is used in the resource tree.

Parameters:

ctx - The context for this provider.

stop

public void stop()

With a call to this method, the provider implementation is notified that it is not used anymore in the resource tree.

update

public void update(long changeSet)

With a call to this method, the provider implementation is notified that any information regarding the registration of the provider has changed. For example, observation listeners might have changed. This method is only called while the provider is used in the resource tree.

Parameters:

changeSet - A bit set of provider info that has changed.

See Also:

ProviderContext.OBSERVATION_LISTENER_CHANGED, ProviderContext.EXCLUDED_PATHS_CHANGED

authenticate

public T authenticate(java.util.Map<java.lang.String,java.lang.Object> authenticationInfo)
               throws LoginException

Authenticate against the resource provider.

Returns a provider context object if authentication is successful. The context object is passed to the resource provider in all messages through the ResourceContext. A valid implementation might return null as the context information.

If authentication fails a LoginException must be thrown.

The returned context object grants access to the provided resources with privileges assigned to the service provided by the calling bundle.

The authenticationInfo map will in general contain the same information as provided to the respective ResourceResolver method. For

The provided authenticationInfo map may be used to provide additional information such as the AUTH_SERVICE_BUNDLE. If this property is provided, additional information like ResourceResolverFactory.SUBSERVICE might be provided, but the ResourceResolverFactory.USER and ResourceResolverFactory.PASSWORD properties provided in the map must be ignored.

The ResourceResolverFactory.USER_IMPERSONATION property is obeyed but requires that the authenticated user has permission to impersonate as the requested user. If such permission is missing, a LoginException is thrown.

The resource resolver implementation will call the logout(Object) method once the resource resolver is closed. However, if the resource provider is already unregistered when the resource resolver is closed, logout can't be called. Therefore the returned state object might implement Closeable. In this case close is called on the state object.

Parameters:

authenticationInfo - A map of further credential information which may be used by the implementation to parameterize how the resource resolver is created.

Returns:

A context data object according to the authenticationInfo.

Throws:

LoginException - If an error occurs authenticating with the provided credential data.

See Also:

Service Authentication

logout

public void logout(T state)

If the provider requires authentication, this method is called with the state of the user returned by authenticate(Map) once the resource resolver is closed.

Parameters:

state - The provider state returned by authenticate(Map).

refresh

public void refresh(ResolveContext<T> ctx)

The provider is updated to reflect the latest state. Resources which have changes pending are not discarded. revert(ResolveContext) can be called to discard changes.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_REFRESHABLE to the value true.

Parameters:

ctx - The ResolveContext.

isLive

public boolean isLive(ResolveContext<T> ctx)

Returns true if this resource provider has not been closed yet and can still be used.

This method will never throw an exception even after the resource provider has been closed

This method is only called for resource providers which have a state and require authentication.

Parameters:

ctx - The ResolveContext.

Returns:

true if the resource provider has not been closed yet and is still active.. Once the resource provider has been closed or is not active anymore, this method returns false.

getParent

public Resource getParent(ResolveContext<T> ctx,
                          Resource child)

Returns the parent resource from this resource provider or null if the resource provider cannot find it. The resource provider must not return cached instances for a resource as the resource resolver will update the resource meta data of the resource at the end of the resolution process and this meta data might be different depending on the full path of resource resolution passed into the resource resolver.

Parameters:

ctx - The ResolveContext.

child - The child resource.

Returns:

null if this provider does not have a resource for the parent.

Throws:

SlingException - may be thrown in case of any problem creating the Resource instance.

getResource

public abstract Resource getResource(ResolveContext<T> ctx,
                                     java.lang.String path,
                                     ResourceContext resourceContext,
                                     Resource parent)

Returns a resource from this resource provider or null if the resource provider cannot find it. The path must have the PROPERTY_ROOT strings as its prefix. The resource provider must not return cached instances for a resource as the resource resolver will update the resource meta data of the resource at the end of the resolution process and this meta data might be different depending on the full path of resource resolution passed into the resource resolver.

Parameters:

ctx - The ResolveContext.

path - The full path of the resource.

resourceContext - Additional information for resolving the resource

parent - Optional parent resource

Returns:

null If this provider does not have a resource for the path.

Throws:

SlingException - may be thrown in case of any problem creating the Resource instance.

listChildren

public abstract java.util.Iterator<Resource> listChildren(ResolveContext<T> ctx,
                                                          Resource parent)

Returns an Iterator of Resource objects loaded from the children of the given Resource. The returned Resource instances are attached to the same ResourceResolver as the given parent resource.

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.

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 SyntheticResource objects whose resource type MUST be set to RESOURCE_TYPE_SYNTHETIC. As with getResource(ResolveContext, String, ResourceContext, Resource) the returned Resource objects must not be cached objects.

Parameters:

ctx - The ResolveContext.

parent - The Resource whose children are requested.

Returns:

An Iterator of Resource objects or null if the resource provider has no children for the given resource.

Throws:

java.lang.NullPointerException - If parent is null.

SlingException - If any error occurs acquiring the child resource iterator.

getAttributeNames

public java.util.Collection<java.lang.String> getAttributeNames(ResolveContext<T> ctx)

Returns a collection of attribute names whose value can be retrieved calling the getAttribute(ResolveContext, String) method.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_ATTRIBUTABLE to the value true.

Parameters:

ctx - The ResolveContext.

Returns:

A collection of attribute names or null

Throws:

java.lang.IllegalStateException - if this resource provider has already been closed.

getAttribute

public java.lang.Object getAttribute(ResolveContext<T> ctx,
                                     java.lang.String name)

Returns the value of the given resource provider attribute or null if the attribute is not set or not visible (as e.g. security sensitive attributes).

This method is only called if the provider supports this and indicates it by setting the PROPERTY_ATTRIBUTABLE to the value true.

Parameters:

ctx - The ResolveContext.

name - The name of the attribute to access

Returns:

The value of the attribute or null if the attribute is not set or not accessible.

Throws:

java.lang.IllegalStateException - if this resource provider has already been closed.

create

public Resource create(ResolveContext<T> ctx,
                       java.lang.String path,
                       java.util.Map<java.lang.String,java.lang.Object> properties)
                throws PersistenceException

Create a new resource at the given path. The new resource is put into the transient space of this provider until commit(ResolveContext) is called.

A resource provider must value ResourceResolver.PROPERTY_RESOURCE_TYPE to set the resource type of a resource.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_MODIFIABLE to the value true.

Parameters:

ctx - The ResolveContext.

path - The resource path.

properties - Optional properties

Returns:

The new resource.

Throws:

PersistenceException - If anything fails

delete

public void delete(ResolveContext<T> ctx,
                   Resource resource)
            throws PersistenceException

Delete the resource at the given path. This change is kept in the transient space of this provider until commit(ResolveContext) is called.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_MODIFIABLE to the value true.

Parameters:

ctx - The ResolveContext.

resource - The resource to delete.

Throws:

PersistenceException - If anything fails

revert

public void revert(ResolveContext<T> ctx)

Revert all transient changes: create, delete and updates.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_MODIFIABLE to the value true.

Parameters:

ctx - The ResolveContext.

commit

public void commit(ResolveContext<T> ctx)
            throws PersistenceException

Commit all transient changes: create, delete and updates

This method is only called if the provider supports this and indicates it by setting the PROPERTY_MODIFIABLE to the value true.

Parameters:

ctx - The ResolveContext.

Throws:

PersistenceException - If anything fails

hasChanges

public boolean hasChanges(ResolveContext<T> ctx)

Are there any transient changes?

This method is only called if the provider supports this and indicates it by setting the PROPERTY_MODIFIABLE to the value true.

Parameters:

ctx - The ResolveContext.

Returns:

true if there are pending changes.

getQueryLanguageProvider

public QueryLanguageProvider<T> getQueryLanguageProvider()

Get the optional query language provider. If the provider supports this kind of query, it must return a query provider implementation if the provider is active. It should not return a query provider if it is not active. This method is called for each query, therefore the provider implementation might cache the provider object.

Returns:

A query language provider if this resource provider supports this type of querying.

adaptTo

public <AdapterType> AdapterType adaptTo(ResolveContext<T> ctx,
                                         java.lang.Class<AdapterType> type)

Adapts the provider to another type.

Please not that it is explicitly left as an implementation detail whether each call to this method with the same type yields the same object or a new object on each call.

Implementations of this method should document their adapted types as well as their behavior with respect to returning newly created or not instance on each call.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_ADAPTABLE to the value true.

Type Parameters:

AdapterType - The generic type to which this resource is adapted to.

Parameters:

ctx - The ResolveContext.

type - The generic type to which this resource is adapted to.

Returns:

The adapter target or null if the provider cannot be adapt to the requested type.

copy

public boolean copy(ResolveContext<T> ctx,
                    java.lang.String srcAbsPath,
                    java.lang.String destAbsPath)
             throws PersistenceException

This method copies the subgraph rooted at, and including, the resource at srcAbsPath to the new location at destAbsPath and adds it as a child node of the resource at destAbsPath.

Both resources are resources from this provider and the full tree is provided by this provider as well.

The resource at destAbsPath needs to exist, if not a PersistenceException is thrown. If a child resource with the same name already exists at destAbsPath a PersistenceException is thrown.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_MODIFIABLE to the value true.

Parameters:

ctx - The ResolveContext.

srcAbsPath - the path of the resource to be copied.

destAbsPath - the location to which the resource at srcAbsPath is to be copied.

Returns:

true if the provider can perform the copy

Throws:

PersistenceException - If an error occurs.

move

public boolean move(ResolveContext<T> ctx,
                    java.lang.String srcAbsPath,
                    java.lang.String destAbsPath)
             throws PersistenceException

This method moves the subgraph rooted at, and including, the resource at srcAbsPath to the new location at destAbsPath and adds it as a child node of the resource at destAbsPath.

Both resources are resources from this provider and the full tree is provided by this provider as well.

The resource at destAbsPath needs to exist, if not a PersistenceException is thrown. If a child resource with the same name already exists at destAbsPath a PersistenceException is thrown.

This method is only called if the provider supports this and indicates it by setting the PROPERTY_MODIFIABLE to the value true.

Parameters:

ctx - The ResolveContext.

srcAbsPath - the path of the resource to be copied.

destAbsPath - the location to which the resource at srcAbsPath is to be moved.

Returns:

true if the provider can perform the move

Throws:

PersistenceException - If an error occurs.