@ConsumerType public abstract class ResourceProvider<T> extends java.lang.Object
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.
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 and Description |
---|
ResourceProvider() |
Modifier and Type | Method and Description |
---|---|
<AdapterType> |
adaptTo(@NotNull ResolveContext<T> ctx,
@NotNull java.lang.Class<AdapterType> type)
Adapts the provider to another type.
|
T |
authenticate(@NotNull java.util.Map<java.lang.String,java.lang.Object> authenticationInfo)
Authenticate against the resource provider.
|
void |
commit(@NotNull ResolveContext<T> ctx)
Commit all transient changes: create, delete and updates
|
boolean |
copy(@NotNull ResolveContext<T> ctx,
@NotNull java.lang.String srcAbsPath,
@NotNull 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 . |
@NotNull Resource |
create(@NotNull 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(@NotNull ResolveContext<T> ctx,
@NotNull Resource resource)
Delete the resource at the given path.
|
@Nullable java.lang.Object |
getAttribute(@NotNull ResolveContext<T> ctx,
@NotNull 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. |
@Nullable java.util.Collection<java.lang.String> |
getAttributeNames(@NotNull ResolveContext<T> ctx)
Returns a collection of attribute names whose value can be retrieved
calling the
getAttribute(ResolveContext, String) method. |
@Nullable Resource |
getParent(@NotNull ResolveContext<T> ctx,
@NotNull Resource child)
Returns the parent resource from this resource provider or
null if
the resource provider cannot find it. |
@Nullable QueryLanguageProvider<T> |
getQueryLanguageProvider()
Get the optional query language provider.
|
abstract @Nullable Resource |
getResource(@NotNull ResolveContext<T> ctx,
@NotNull java.lang.String path,
@NotNull ResourceContext resourceContext,
@Nullable Resource parent)
Returns a resource from this resource provider or
null if
the resource provider cannot find it. |
boolean |
hasChanges(@NotNull ResolveContext<T> ctx)
Are there any transient changes?
|
boolean |
isLive(@NotNull ResolveContext<T> ctx)
Returns
true if this resource provider has not been closed
yet and can still be used. |
abstract @Nullable java.util.Iterator<Resource> |
listChildren(@NotNull ResolveContext<T> ctx,
@NotNull Resource parent)
|
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(@NotNull ResolveContext<T> ctx,
@NotNull java.lang.String srcAbsPath,
@NotNull 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(@NotNull ResolveContext<T> ctx)
The provider is updated to reflect the latest state.
|
void |
revert(@NotNull ResolveContext<T> ctx)
Revert all transient changes: create, delete and updates.
|
void |
start(@NotNull 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.
|
public static final java.lang.String PROPERTY_ROOT
public static final java.lang.String PROPERTY_NAME
public static final java.lang.String PROPERTY_USE_RESOURCE_ACCESS_SECURITY
false
.
(value is "provider.useResourceAccessSecurity")public static final java.lang.String AUTHENTICATE_NO
PROPERTY_AUTHENTICATE
PROPERTY_AUTHENTICATE
,
Constant Field Valuespublic static final java.lang.String AUTHENTICATE_REQUIRED
PROPERTY_AUTHENTICATE
indicating authentication is required.PROPERTY_AUTHENTICATE
,
Constant Field Valuespublic static final java.lang.String AUTHENTICATE_LAZY
PROPERTY_AUTHENTICATE
indicating authentication is needed
and will be done on demand.PROPERTY_AUTHENTICATE
,
Constant Field Valuespublic static final java.lang.String PROPERTY_AUTHENTICATE
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")public static final java.lang.String PROPERTY_MODIFIABLE
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")public static final java.lang.String PROPERTY_ADAPTABLE
true
, the resource resolver will use this provider
for the adaptTo() operation.
Boolean service property, default value is false
.
(value is "provider.adaptable")public static final java.lang.String PROPERTY_REFRESHABLE
true
, the resource resolver will call refresh(ResolveContext)
when it's refreshed itself.
Boolean service property, default value is false
.
(value is "provider.refreshable")public static final java.lang.String PROPERTY_ATTRIBUTABLE
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")public static final java.lang.String AUTH_SERVICE_BUNDLE
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
.
public static final java.lang.String AUTH_ADMIN
ResourceResolverFactory.getAdministrativeResourceResolver(Map)
.public static final java.lang.String AUTH_CLONE
public static final java.lang.String RESOURCE_TYPE_SYNTHETIC
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").public void start(@NotNull @NotNull ProviderContext ctx)
ctx
- The context for this provider.public void stop()
public void update(long changeSet)
changeSet
- A bit set of provider info that has changed.ProviderContext.OBSERVATION_LISTENER_CHANGED
,
ProviderContext.EXCLUDED_PATHS_CHANGED
@Nullable public T authenticate(@NotNull @NotNull java.util.Map<java.lang.String,java.lang.Object> authenticationInfo) throws LoginException
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.
authenticationInfo
- A map of further credential information which
may be used by the implementation to parameterize how the
resource resolver is created.authenticationInfo
.LoginException
- If an error occurs authenticating with the
provided credential data.public void logout(@Nullable T state)
authenticate(Map)
once the resource resolver is closed.state
- The provider state returned by authenticate(Map)
.public void refresh(@NotNull @NotNull ResolveContext<T> ctx)
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
.
ctx
- The ResolveContext
.public boolean isLive(@NotNull @NotNull ResolveContext<T> ctx)
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.
ctx
- The ResolveContext
.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
.@Nullable public @Nullable Resource getParent(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull Resource child)
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.ctx
- The ResolveContext
.child
- The child resource.null
if this provider does not have a resource for
the parent.SlingException
- may be thrown in case of any problem creating the Resource
instance.@Nullable public abstract @Nullable Resource getResource(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull java.lang.String path, @NotNull @NotNull ResourceContext resourceContext, @Nullable @Nullable Resource parent)
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.ctx
- The ResolveContext
.path
- The full path of the resource.resourceContext
- Additional information for resolving the resourceparent
- Optional parent resourcenull
If this provider does not have a resource for
the path.SlingException
- may be thrown in case of any problem creating the Resource
instance.@Nullable public abstract @Nullable java.util.Iterator<Resource> listChildren(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull Resource parent)
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.
ctx
- The ResolveContext
.parent
- The Resource
whose children are requested.Iterator
of Resource
objects or null
if the resource
provider has no children for the given resource.java.lang.NullPointerException
- If parent
is null
.SlingException
- If any error occurs acquiring the child resource iterator.@Nullable public @Nullable java.util.Collection<java.lang.String> getAttributeNames(@NotNull @NotNull ResolveContext<T> ctx)
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
.
ctx
- The ResolveContext
.null
java.lang.IllegalStateException
- if this resource provider has already been
closed.@Nullable public @Nullable java.lang.Object getAttribute(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull java.lang.String name)
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
.
ctx
- The ResolveContext
.name
- The name of the attribute to accessnull
if the attribute
is not set or not accessible.java.lang.IllegalStateException
- if this resource provider has already been closed.@NotNull public @NotNull Resource create(@NotNull @NotNull ResolveContext<T> ctx, java.lang.String path, java.util.Map<java.lang.String,java.lang.Object> properties) throws PersistenceException
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
.
ctx
- The ResolveContext
.path
- The resource path.properties
- Optional propertiesPersistenceException
- If anything failspublic void delete(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull Resource resource) throws PersistenceException
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
.
ctx
- The ResolveContext
.resource
- The resource to delete.PersistenceException
- If anything failspublic void revert(@NotNull @NotNull ResolveContext<T> ctx)
This method is only called if the provider supports this and indicates
it by setting the PROPERTY_MODIFIABLE
to the value true
.
ctx
- The ResolveContext
.public void commit(@NotNull @NotNull ResolveContext<T> ctx) throws PersistenceException
This method is only called if the provider supports this and indicates
it by setting the PROPERTY_MODIFIABLE
to the value true
.
ctx
- The ResolveContext
.PersistenceException
- If anything failspublic boolean hasChanges(@NotNull @NotNull ResolveContext<T> ctx)
This method is only called if the provider supports this and indicates
it by setting the PROPERTY_MODIFIABLE
to the value true
.
ctx
- The ResolveContext
.true
if there are pending changes.@Nullable public @Nullable QueryLanguageProvider<T> getQueryLanguageProvider()
@Nullable public <AdapterType> AdapterType adaptTo(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull java.lang.Class<AdapterType> 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
.
AdapterType
- The generic type to which this resource is adapted to.ctx
- The ResolveContext
.type
- The generic type to which this resource is adapted to.null
if the provider cannot
be adapt to the requested type.public boolean copy(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull java.lang.String srcAbsPath, @NotNull @NotNull java.lang.String destAbsPath) throws PersistenceException
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
.
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.true
if the provider can perform the copyPersistenceException
- If an error occurs.public boolean move(@NotNull @NotNull ResolveContext<T> ctx, @NotNull @NotNull java.lang.String srcAbsPath, @NotNull @NotNull java.lang.String destAbsPath) throws PersistenceException
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
.
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.true
if the provider can perform the movePersistenceException
- If an error occurs.Copyright © 2010 - 2020 Adobe. All Rights Reserved