@ProviderType public interface ResourceResolver extends Adaptable, Closeable
ResourceResolver
defines the service API which may be used
to resolve Resource
objects. The resource resolver is available to
the request processing servlet through the
SlingHttpServletRequest.getResourceResolver()
method.
A resource resolver can also be created through the ResourceResolverFactory
.
The ResourceResolver
is also an Adaptable
to get
adapters to other types. A JCR based resource resolver might support adapting
to the JCR Session used by the resolver to access the JCR Repository.
A ResourceResolver
is generally not thread safe! As a
consequence, an application which uses the resolver, its returned resources
and/or objects resulting from adapting either the resolver or a resource,
must provide proper synchronization to ensure no more than one thread
concurrently operates against a single resolver, resource or resulting
objects.
Accessing Resources
This interface defines two kinds of methods to access resources: The
resolve
methods and the getResource
methods. The
difference lies in the algorithm applied to find the requested resource and
in the behavior in case a resource cannot be found:
Method Kind | Access Algorithm | Missing Resource |
---|---|---|
resolve | Path is always assumed to be absolute. Uses elaborate resource resolution algorithm. This kind of method is intended to resolve request URLs to resources. | Returns NonExistingResource |
getResource | Directly access resources with absolute path. For relative paths, the
search path is applied. This method is intended to
be used by request processing scripts to access further resources as
required. |
Returns null |
Lifecycle
A Resource Resolver has a life cycle which begins with the creation of the
Resource Resolver using any of the factory methods and ends with calling the
close()
method. It is very important to call the close()
method once the resource resolver is not used any more to ensure any system
resources are properly cleaned up.
A Resource Resolver may also be closed implicitly if the ResourceResolverFactory
which was used to create this resolver is no longer active.
To check whether a Resource Resolver can still be used, the isLive()
method can be called.
A ResourceResolver
is only valid for as long as the
ResourceResolverFactory
that created this instance exists. The
same applies in general to all objects returned by this instance,
especially for all resources. If the ResourceResolverFactory
does not exist anymore, the resource resolver instances becomes invalid.
Resource Resolver Attributes
The authentication info properties provided to the
ResourceResolverFactory.getResourceResolver(Map)
,
ResourceResolverFactory.getAdministrativeResourceResolver(Map)
, or
clone(Map)
are available through the getAttributeNames()
and getAttribute(String)
methods with the exception of security
sensitive properties like ResourceResolverFactory.PASSWORD
which is
not exposed.
Modifier and Type | Field and Description |
---|---|
static String |
PROPERTY_RESOURCE_TYPE
This is the suggested property to be used for setting the resource type
of a resource during either creation (
create(Resource, String, Map) )
or modifying (ModifiableValueMap ). |
static String |
REQUEST_ATTR_WORKSPACE_INFO
Deprecated.
|
static String |
USER_IMPERSONATOR
The name of the resource resolver attribute which is set if the resource
resolver has been impersonated as per the
ResourceResolverFactory.USER_IMPERSONATION property. |
Modifier and Type | Method and Description |
---|---|
ResourceResolver |
clone(Map<String,Object> authenticationInfo)
Returns a new
ResourceResolver instance based on the given
authenticationInfo map and the original authentication info
used to create this instance. |
void |
close()
Close this resource resolver.
|
void |
commit()
Persist all pending changes.
|
Resource |
copy(String srcAbsPath,
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(Resource parent,
String name,
Map<String,Object> properties)
Add a child resource to the given parent resource
|
void |
delete(Resource resource)
Delete the resource
Deleting a non existing resource leads to no operation nor exception.
|
Iterator<Resource> |
findResources(String query,
String language)
Searches for resources using the given query formulated in the given
language.
|
Object |
getAttribute(String name)
Returns the value of the given resource resolver attribute or
null if the attribute is not set (or not visible as is the
case of the ResourceResolverFactory.PASSWORD or other security
sensitive attributes). |
Iterator<String> |
getAttributeNames()
Returns an iterator of attribute names whose value can be retrieved
calling the
getAttribute(String) method. |
Iterable<Resource> |
getChildren(Resource parent)
|
Resource |
getParent(Resource child)
Returns the parent resource of this resource.
|
String |
getParentResourceType(Resource resource)
Returns the super type of the given resource.
|
String |
getParentResourceType(String resourceType)
Returns the super type of the given resource type.
|
Resource |
getResource(Resource base,
String path)
Returns a
Resource object for data located at the given path. |
Resource |
getResource(String path)
Returns a
Resource object for data located at the given path. |
String[] |
getSearchPath()
Returns the search path used by the
getResource(String) method
to search for resources by relative path. |
String |
getUserID()
Get the user ID, if any, associated with this resource resolver.
|
boolean |
hasChanges()
Are there any pending changes?
|
boolean |
hasChildren(Resource resource)
Checks if the specified resource has any direct child resources.
|
boolean |
isLive()
Returns
true if this resource resolver is still usable. |
boolean |
isResourceType(Resource resource,
String resourceType)
Returns
true if the resource type or any of the resource's
super type(s) equals the given resource type. |
Iterator<Resource> |
listChildren(Resource parent)
|
String |
map(javax.servlet.http.HttpServletRequest request,
String resourcePath)
Returns an URL mapped from the (resource) path applying the reverse
mapping used by the
resolve(HttpServletRequest, String) such
that when the path is given to the
resolve(HttpServletRequest, String) method the same resource is
returned. |
String |
map(String resourcePath)
Returns a path mapped from the (resource) path applying the reverse
mapping used by the
resolve(String) such that when the path is
given to the resolve(String) method the same resource is
returned. |
Resource |
move(String srcAbsPath,
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 . |
Iterator<Map<String,Object>> |
queryResources(String query,
String language)
Queries the storage using the given query formulated in the given
language.
|
void |
refresh()
The resolver is updated to reflect the latest state.
|
Resource |
resolve(javax.servlet.http.HttpServletRequest request)
Deprecated.
as of 2.0.4, use
resolve(HttpServletRequest, String)
instead. |
Resource |
resolve(javax.servlet.http.HttpServletRequest request,
String absPath)
Resolves the resource from the given
absPath optionally
taking HttpServletRequest into account, such as the value of
the Host request header. |
Resource |
resolve(String absPath)
Resolves the resource from the given absolute path.
|
void |
revert()
Revert all pending changes.
|
@Deprecated static final String REQUEST_ATTR_WORKSPACE_INFO
resolve(HttpServletRequest)
and
resolve(HttpServletRequest, String)
if not the default workspace
should be used to resolve the resource.static final String USER_IMPERSONATOR
ResourceResolverFactory.USER_IMPERSONATION
property. The value of
this attribute is the name of the primary user provided to the resource
resolver factory method.static final String PROPERTY_RESOURCE_TYPE
create(Resource, String, Map)
)
or modifying (ModifiableValueMap
).
However the exact way to set the resource type of a resource is defined
by the underlying resource provider. It should value this property but
is not required to do so.@Nonnull Resource resolve(@Nonnull javax.servlet.http.HttpServletRequest request, @Nonnull String absPath)
absPath
optionally
taking HttpServletRequest
into account, such as the value of
the Host
request header. Returns a
NonExistingResource
if the path cannot be resolved to an existing
and accessible resource.
The difference between this method and the resolve(String)
method is, that this method may take request properties like the scheme,
the host header or request parameters into account to resolve the
resource.
request
- The http servlet request object providing more hints at
how to resolve the absPath
. This parameter may be
null
in which case the implementation should use
reasonable defaults.absPath
- The absolute path to be resolved to a resource. If this
parameter is null
, it is assumed to address the
root of the resource tree. If the path is relative it is
assumed relative to the root, that is a slash is prepended to
the path before resolving it.Resource
addressed by the absPath
or a
NonExistingResource
if no such resource can be resolved.SlingException
- Or a subclass thereof may be
thrown if an error occurs trying to resolve the resource.IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull Resource resolve(@Nonnull String absPath)
NonExistingResource
if the path cannot be resolved to an existing
and accessible resource.
This method is intended to apply the same algorithm to the absolute path
as is used by the resolve(HttpServletRequest)
method except for
cases where the latter uses request property such as request headers or
request parameters to resolve a resource.
It is ok for the implementation of this method to just call the
resolve(HttpServletRequest, String)
method with
null
as the request argument.
absPath
- The absolute path to be resolved to a resource. If this
parameter is null
, it is assumed to address the
root of the resource tree. If the path is relative it is
assumed relative to the root, that is a slash is prepended to
the path before resolving it.Resource
addressed by the absPath
or a
NonExistingResource
if no such resource can be resolved.SlingException
- Or a subclass thereof may be
thrown if an error occurs trying to resolve the resource.IllegalStateException
- if this resource resolver has already been
closed
.@Deprecated @Nonnull Resource resolve(@Nonnull javax.servlet.http.HttpServletRequest request)
resolve(HttpServletRequest, String)
instead.HttpServletRequest
.
Returns a NonExistingResource
if the path cannot be resolved to
an existing and accessible resource.
This method is deprecated as of API version 2.0.4 and should not be used
anymore. Implementations are expected to implement this method calling
the resolve(HttpServletRequest, String)
where the
absPath
argument is the result of calling the
getPathInfo()
on the request
object.
request
- The http servlet request object used to resolve the
resource for. This must not be null
.Resource
addressed by
HttpServletRequest.getPathInfo()
or a
NonExistingResource
if no such resource can be resolved.NullPointerException
- If request
is null
.SlingException
- Or a subclass thereof may be
thrown if an error occurs trying to resolve the resource.IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull String map(@Nonnull String resourcePath)
resolve(String)
such that when the path is
given to the resolve(String)
method the same resource is
returned.
Note, that technically the resourcePath
need not refer to an
existing resource. This method just applies the mappings and returns the
resulting string. If the resourcePath
does not address an
existing resource roundtripping may of course not work and calling
resolve(String)
with the path returned may return
null
.
This method is intended as the reverse operation of the
resolve(String)
method.
resourcePath
- The path for which to return a mapped path.IllegalStateException
- if this resource resolver has already been
closed
.@CheckForNull String map(@Nonnull javax.servlet.http.HttpServletRequest request, @Nonnull String resourcePath)
resolve(HttpServletRequest, String)
such
that when the path is given to the
resolve(HttpServletRequest, String)
method the same resource is
returned.
Note, that technically the resourcePath
need not refer to an
existing resource. This method just applies the mappings and returns the
resulting string. If the resourcePath
does not address an
existing resource roundtripping may of course not work and calling
resolve(HttpServletRequest, String)
with the path returned may
return null
.
This method is intended as the reverse operation of the
resolve(HttpServletRequest, String)
method. As such the URL
returned is expected to be an absolute URL including scheme, host, any
servlet context path and the actual path used to resolve the resource.
request
- The http servlet request object which may be used to apply
more mapping functionality.resourcePath
- The path for which to return a mapped path.IllegalStateException
- if this resource resolver has already been
closed
.@CheckForNull Resource getResource(@Nonnull String path)
Resource
object for data located at the given path.
This specification does not define the location for resources or the
semantics for resource paths. For an implementation reading content from
a Java Content Repository, the path could be a
javax.jcr.Item
path from which the resource object is
loaded. In contrast to the resolve(String)
method, this method
does not apply any logic to the path, so the path is used as-is to fetch
the content.
path
- The absolute path to the resource object to be loaded. The
path may contain relative path specifiers like .
(current location) and ..
(parent location),
which are resolved by this method. If the path is relative,
that is the first character is not a slash, implementations
are expected to apply a search path algorithm to resolve the
relative path to a resource.Resource
object loaded from the path or
null
if the path does not resolve to a resource.SlingException
- If an error occurs trying to
load the resource object from the path.IllegalStateException
- if this resource resolver has already been
closed
.@CheckForNull Resource getResource(Resource base, @Nonnull String path)
Resource
object for data located at the given path.
This specification does not define the location for resources or the
semantics for resource paths. For an implementation reading content from
a Java Content Repository, the path could be a
javax.jcr.Item
path from which the resource object is
loaded.
base
- The base Resource
against which a relative path
argument given by path
is resolved. This
parameter may be null
if the path
is
known to be absolute.path
- The path to the resource object to be loaded. If the path is
relative, i.e. does not start with a slash (/
),
the resource relative to the given base
resource
is returned. The path may contain relative path specifiers
like .
(current location) and ..
(parent location), which are resolved by this method.Resource
object loaded from the path or
null
if the path does not resolve to a resource.SlingException
- If an error occurs trying to
load the resource object from the path or if
base
is null
and path
is relative.IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull String[] getSearchPath()
getResource(String)
method
to search for resources by relative path. If no search path is set an
empty array is returned.
The returned array of strings is a copy of the internal value, so modifications to this array have no influence on the operation of the ResourceResolver.
The search path of a resource resolver never changes during the lifetime of the resource resolver. Therefore clients may call this method once and use the stored value together with this resource resolver.
Each entry in the array 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.
IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull Iterator<Resource> listChildren(@Nonnull Resource parent)
Iterator
of Resource
objects loaded from
the children of the given Resource
.
This specification does not define what the term "child" means. This is
left to the implementation to define. For example an implementation
reading content from a Java Content Repository, the children could be the
Resource
objects loaded from child items of the Item
of the given Resource
.
parent
- The Resource
whose children are requested.Iterator
of Resource
objects.NullPointerException
- If parent
is null
.SlingException
- If any error occurs acquiring
the child resource iterator.IllegalStateException
- if this resource resolver has already been
closed
.@CheckForNull Resource getParent(@Nonnull Resource child)
This method is implemented by getting the parent resource path first
calling the ResourceUtil.getParent(String)
method and then to
retrieve that resource.
child
- The Resource
whose parent is requested.null
.NullPointerException
- If child
is null
.SlingException
- If any error occurs acquiring
the parent resource.IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull Iterable<Resource> getChildren(@Nonnull Resource parent)
Iterable
of Resource
objects loaded from
the children of the given Resource
.
This specification does not define what the term "child" means. This is
left to the implementation to define. For example an implementation
reading content from a Java Content Repository, the children could be the
Resource
objects loaded from child items of the Item
of the given Resource
.
parent
- The Resource
whose children are requested.Iterable
of Resource
objects.NullPointerException
- If parent
is null
.SlingException
- If any error occurs acquiring
the child resource iterator.IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull Iterator<Resource> findResources(@Nonnull String query, String language)
The semantic meaning of the query and language depend on the actual
implementation and storage used for the resources. For JCR repository
being used as storage, the query and language parameters are used to
create a JCR Query
through the QueryManager
.
The result returned is then based on the NodeIterator
provided by the query result.
query
- The query string to use to find the resources.language
- The language in which the query is formulated. The
language should always be specified. However for
compatibility with older version, if no language
is specified, "xpath" is used.Iterator
of Resource
objects matching the
query.QuerySyntaxException
- If the query is not syntactically correct
according to the query language indicator.SlingException
- If an error occurs querying
for the resources.IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull Iterator<Map<String,Object>> queryResources(@Nonnull String query, String language)
The semantic meaning of the query and language depend on the actual
implementation and storage used for the resources. For JCR repository
being used as storage, the query and language parameters are used to
create a JCR Query
through the QueryManager
.
The result returned is then based on the RowIterator
provided by the query result. The map returned for each row is indexed by
the column name and the column value is the JCR Value
object
converted into the respective Java object, such as Boolean
for a value of property type Boolean.
query
- The query string to use to find the resources.language
- The language in which the query is formulated. The
language should always be specified. However for
compatibility with older version, if no language
is specified, "xpath" is used.Iterator
of Map
instances providing
access to the query result.QuerySyntaxException
- If the query is not syntactically correct
according to the query language indicator.SlingException
- If an error occurs querying
for the resources.IllegalStateException
- if this resource resolver has already been
closed
.boolean hasChildren(@Nonnull Resource resource)
resource
- the resource to check for direct childrentrue
if the resource has any child resourcesIllegalStateException
- if this resource resolver has already been
closed
.@Nonnull ResourceResolver clone(Map<String,Object> authenticationInfo) throws LoginException
ResourceResolver
instance based on the given
authenticationInfo
map and the original authentication info
used to create this instance.
The new resource resolver is created according to the following algorithm:
Map<String, Object> newAuthenticationInfo = new HashMap( authenticationInfoOfThisInstance); newAuthenticationInfo.addAll(authenticationInfo); return resourceResolverFactory.getResourceResolver(newAuthenticationInfo);
authenticationInfo
- The map or credential data to overlay the
original credential data with for the creation of a new
resource resolver. This may be null
in which case
the same credential data is used as was used to create this
instance.ResourceResolver
LoginException
- If an error occurs creating the new
ResourceResolver
with the provided credential
data.IllegalStateException
- if this resource resolver has already been
closed
.boolean isLive()
true
if this resource resolver is still usable.
This method tests different things like if it has not been closed
yet or if any of the used resource providers is not usable anymore.
Unlike the other methods defined in this interface, this method will
never throw an exception even after the resource resolver has been
closed
.
true
if the resource resolver is still usable.
Once the resource resolver has been closed or a used resource
provider has been unregistered, this method returns false
.void close()
ResourceResolverFactory
which was used to create this resolver is no longer active or
any of the used resource providers is no longer active.close
in interface AutoCloseable
close
in interface Closeable
Resource Resolver (section lifecycle)
@CheckForNull String getUserID()
IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull Iterator<String> getAttributeNames()
getAttribute(String)
method. This iterator will not
include any attributes which are not accessible.IllegalStateException
- if this resource resolver has already been
closed
.@CheckForNull Object getAttribute(@Nonnull String name)
null
if the attribute is not set (or not visible as is the
case of the ResourceResolverFactory.PASSWORD
or other security
sensitive attributes).name
- The name of the attribute to accessnull
if the attribute
is not set or not accessible.NullPointerException
- if name
is null
.IllegalStateException
- if this resource resolver has already been
closed
.void delete(@Nonnull Resource resource) throws PersistenceException
resource
- The resource to deleteNullPointerException
- if the resource parameter is nullUnsupportedOperationException
- If the resource provider does not allow to
delete this resource.PersistenceException
- If the operation fails.IllegalStateException
- if this resource resolver has already been
closed
.@Nonnull Resource create(@Nonnull Resource parent, @Nonnull String name, Map<String,Object> properties) throws PersistenceException
parent
- The parent resourcename
- The name of the child resource - this is a plain name, not a path!properties
- Optional properties for the resourceNullPointerException
- if the resource parameter or name parameter is nullIllegalArgumentException
- if the name contains a slashUnsupportedOperationException
- If the resource provider does not allow to
create a resource at that location.PersistenceException
- If the operation fails.IllegalStateException
- if this resource resolver has already been
closed
.void revert()
IllegalStateException
- if this resource resolver has already been
closed
.void commit() throws PersistenceException
PersistenceException
- If persisting the changes fails.IllegalStateException
- if this resource resolver has already been
closed
.boolean hasChanges()
true
if there are pending changes.IllegalStateException
- if this resource resolver has already been
closed
.@CheckForNull String getParentResourceType(Resource resource)
Resource.getResourceSuperType()
. If that returns
null
getParentResourceType(String)
is invoked with the resource type of the resource.resource
- The resource to return the resource super type for.null
. This
method also returns null
if the
provided resource is null
IllegalStateException
- if this resource resolver has already been
closed
.@CheckForNull String getParentResourceType(String resourceType)
Resource.getResourceSuperType()
method
is called.resourceType
- The resource type whose super type is to be returned.resourceType
or
null
if the resource given by the resource type does not exist or
if it returns null
for its super type. It also returns
null
if resourceType
is null.IllegalStateException
- if this resource resolver has already been
closed
.boolean isResourceType(Resource resource, String resourceType)
true
if the resource type or any of the resource's
super type(s) equals the given resource type.
In case the type of the given resource or the given resource type starts with one of the resource resolver's search paths
it is converted to a relative resource type by stripping off the resource resolver's search path
before doing the comparison.resource
- The resource to checkresourceType
- The resource type to check this resource against.true
if the resource type or any of the resource's
super type(s) equals the given resource type. false
is also returned if resource
orresourceType
are null
.IllegalStateException
- if this resource resolver has already been
closed
.void refresh()
IllegalStateException
- if this resource resolver has already been
closed
.Resource copy(String srcAbsPath, String destAbsPath) throws PersistenceException
srcAbsPath
to the new location at destAbsPath
and
adds it as a child node of the resource at destAbsPath
.
If the copy operation is within a single resource provider, the resource provider
can use an optimized copy operation. Otherwise the resource resolver copies resources
from one provider to another.
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. If the resource at srcAbsPath
does not exist,
a PersistenceException
is thrown.srcAbsPath
- the path of the resource to be copied.destAbsPath
- the location to which the resource at
srcAbsPath
is to be copied.PersistenceException
- If an error occurs.UnsupportedOperationException
- If one of the destination resource providers does
not allow to create a resource at that location.IllegalStateException
- if this resource resolver has already been
closed
.Resource move(String srcAbsPath, String destAbsPath) throws PersistenceException
srcAbsPath
to the new location at destAbsPath
and
adds it as a child node of the resource at destAbsPath
.
If the move operation is within a single resource provider, the resource provider
can use an optimized move operation. Otherwise the resource resolver moves resources
from one provider to another.
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. If the resource at srcAbsPath
does not exist,
a PersistenceException
is thrown.srcAbsPath
- the path of the resource to be copied.destAbsPath
- the location to which the resource at
srcAbsPath
is to be moved.PersistenceException
- If an error occurs.UnsupportedOperationException
- If one of the destination resource providers does
not allow to create a resource at that location.IllegalStateException
- if this resource resolver has already been
closed
.Copyright © 2017 The Apache Software Foundation. All rights reserved.