Package org.apache.sling.api.resource

# Class ResourceUtil

java.lang.Object
org.apache.sling.api.resource.ResourceUtil

public class ResourceUtil extends Object
The `ResourceUtil` class provides helper methods dealing with resources.

This class is not intended to be extended or instantiated because it just provides static utility methods not intended to be overwritten.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`ResourceUtil.BatchResourceRemover`
A batch resource remover deletes resources in batches.

## Constructor Summary

Constructors
Constructor
Description
`ResourceUtil()`

## Method Summary

Modifier and Type
Method
Description
`static <T> @NotNull Iterator<T>`
`adaptTo(@NotNull Iterator<Resource> iterator, Class<T> type)`
Return an iterator for objects of the specified type.
`static String`
`createUniqueChildName(Resource parent, String name)`
Create a unique name for a child of the `parent`.
`static @NotNull String`
`escapeName(@NotNull String name)`
Escapes the given `name` for use in a resource name.
`static @Nullable String`
`findResourceSuperType(@NotNull Resource resource)`
Deprecated.
Use `ResourceResolver.getParentResourceType(Resource)`
`static @NotNull ResourceUtil.BatchResourceRemover`
`getBatchResourceRemover(int threshold)`
Create a batch resource remover.
`static @NotNull String`
`getName(@NotNull String path)`
Utility method returns the name of the given `path`, which is normalized by `normalize(String)` before resolving the name.
`static @NotNull String`
`getName(@NotNull Resource rsrc)`
Deprecated.
since 2.1.0, use `Resource.getName()` instead
`static @NotNull Resource`
`getOrCreateResource(@NotNull ResourceResolver resolver, @NotNull String path, String resourceType, String intermediateResourceType, boolean autoCommit)`
Creates or gets the resource at the given path.
`static @NotNull Resource`
`getOrCreateResource(@NotNull ResourceResolver resolver, @NotNull String path, Map<String,Object> resourceProperties, String intermediateResourceType, boolean autoCommit)`
Creates or gets the resource at the given path.
`static @Nullable String`
`getParent(@NotNull String path)`
Utility method returns the parent path of the given `path`, which is normalized by `normalize(String)` before resolving the parent.
`static @Nullable Resource`
`getParent(@NotNull Resource rsrc)`
Deprecated.
since 2.1.0, use `Resource.getParent()` instead
`static String`
`getParent(String path, int level)`
Utility method returns the ancestor's path at the given `level` relative to `path`, which is normalized by `normalize(String)` before resolving the ancestor.
`static @Nullable String`
`getResourceSuperType(@NotNull ResourceResolver resourceResolver, String resourceType)`
Deprecated.
Use `ResourceResolver.getParentResourceType(String)`
`static @NotNull ValueMap`
`getValueMap(Resource res)`
Returns an `ValueMap` object for the given `Resource`.
`static boolean`
`isA(@NotNull Resource resource, String resourceType)`
Deprecated.
Use `ResourceResolver.isResourceType(Resource, String)`
`static boolean`
`isNonExistingResource(@NotNull Resource res)`
Returns `true` if the resource `res` is a non-existing resource.
`static boolean`
`isStarResource(@NotNull Resource res)`
Returns `true` if the resource `res` is a "star resource".
`static boolean`
`isSyntheticResource(@NotNull Resource res)`
Returns `true` if the resource `res` is a synthetic resource.
`static @NotNull Iterator<Resource>`
`listChildren(@NotNull Resource parent)`
Deprecated.
since 2.1.0, use `Resource.listChildren()` instead
`static @Nullable String`
`normalize(@NotNull String path)`
Resolves relative path segments '.' and '..' in the path.
`static @NotNull String`
`resourceTypeToPath(@NotNull String type)`
Helper method, which returns the given resource type as returned from the `Resource.getResourceType()` as a relative path.
`static @NotNull String`
`unescapeName(@NotNull String escapedName)`
Unescapes the given `escapedName` previously escaped using `escapeName(String)`.
`static @NotNull Resource`
`unwrap(@NotNull Resource rsrc)`
Unwrap the resource and return the wrapped implementation.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### ResourceUtil

public ResourceUtil()

## Method Details

### normalize

@Nullable public static @Nullable String normalize(@NotNull @NotNull String path)
Resolves relative path segments '.' and '..' in the path. The path can either be relative or absolute. Relative paths are treated the same as an absolute path. Returns `null` if not possible (for example .. points above root).

Parameters:
  `path` - The path to normalize
Returns:
  The normalized path or `null`.

### getParent

@Nullable public static @Nullable String getParent(@NotNull @NotNull String path)
Utility method returns the parent path of the given `path`, which is normalized by `normalize(String)` before resolving the parent.

Parameters:
  `path` - The path whose parent is to be returned.
Returns:
  `null` if `path` is the root path ( `/`) or if `path` is a single name containing no slash (`/`) characters.
Throws:
  `IllegalArgumentException` - If the path cannot be normalized by the `normalize(String)` method.
  `NullPointerException` - If `path` is `null`.

### getParent

public static String getParent(String path, int level)
Utility method returns the ancestor's path at the given `level` relative to `path`, which is normalized by `normalize(String)` before resolving the ancestor.

- `level` = 0 returns the `path`.
- `level` = 1 returns the parent of `path`, if it exists, `null` otherwise.
- `level` = 2 returns the grandparent of `path`, if it exists, `null` otherwise.

Parameters:
  `path` - The path whose ancestor is to be returned.
  `level` - The relative level of the ancestor, relative to `path`.
Returns:
  `null` if `path` doesn't have an ancestor at the specified `level`.
Throws:
  `IllegalArgumentException` - If the path cannot be normalized by the `normalize(String)` method or if `level` < 0.
  `NullPointerException` - If `path` is `null`.
Since:
  2.2 (Sling API Bundle 2.2.0)

### getParent

@Deprecated @Nullable public static @Nullable Resource getParent(@NotNull @NotNull Resource rsrc)
Deprecated.
since 2.1.0, use `Resource.getParent()` instead
Utility method returns the parent resource of the resource.

Parameters:
  `rsrc` - The resource to get the parent of.
Returns:
  The parent resource or null if the rsrc is the root.
Throws:
  `NullPointerException` - If `rsrc` is `null`.
  `SlingException` - If an error occurs trying to get the resource object from the path.
  `IllegalStateException` - if the resource resolver has already been closed}.

### getName

@Deprecated @NotNull public static @NotNull String getName(@NotNull @NotNull Resource rsrc)
Deprecated.
since 2.1.0, use `Resource.getName()` instead
Utility method returns the name of the resource.

Parameters:
  `rsrc` - The resource to get the name from.
Returns:
  The name of the resource
Throws:
  `NullPointerException` - If `rsrc` is `null`.

### getName

@NotNull public static @NotNull String getName(@NotNull @NotNull String path)
Utility method returns the name of the given `path`, which is normalized by `normalize(String)` before resolving the name.

Parameters:
  `path` - The path whose name (the last path element) is to be returned.
Returns:
  The empty string if `path` is the root path ( `/`) or if `path` is a single name containing no slash (`/`) characters.
Throws:
  `IllegalArgumentException` - If the path cannot be normalized by the `normalize(String)` method.
  `NullPointerException` - If `path` is `null`.

### escapeName

@NotNull public static @NotNull String escapeName(@NotNull @NotNull String name)
Escapes the given `name` for use in a resource name. It escapes all invalid characters according to Sling API, i.e. it escapes the slash and names only consisting of dots. It uses Java UTF-16 unicode escape sequences for those characters.

Parameters:
  `name` -
Returns:
  the escaped name
Since:
  2.14.0 (Sling API Bundle 3.0.0)
See Also:
  - `ResourceResolver.create(Resource, String, Map)`
  - `SyntheticResource(ResourceResolver, String, String)`
  - RFC 5137, section 6.3

### unescapeName

@NotNull public static @NotNull String unescapeName(@NotNull @NotNull String escapedName)
Unescapes the given `escapedName` previously escaped using `escapeName(String)`. It replaces the unicode escape sequences with the original characters.

Parameters:
  `escapedName` - The escaped name to unescape.
Returns:
  The unescaped name.
Since:
  2.14.0 (Sling API Bundle 3.0.0)
See Also:
  - `Resource.getName()`
  - RFC 5137, section 6.3

### isSyntheticResource

public static boolean isSyntheticResource(@NotNull @NotNull Resource res)
Returns `true` if the resource `res` is a synthetic resource.

This method checks whether the resource is an instance of the `org.apache.sling.resource.SyntheticResource` class.

Parameters:
  `res` - The `Resource` to check whether it is a synthetic resource.
Returns:
  `true` if `res` is a synthetic resource. `false` is returned if `res` is `null` or not an instance of the `org.apache.sling.resource.SyntheticResource` class.

### isStarResource

public static boolean isStarResource(@NotNull @NotNull Resource res)
Returns `true` if the resource `res` is a "star resource". A star resource is a resource returned from the `ResourceResolver.resolve(HttpServletRequest)` whose path terminates in a `/*`. Generally such resource result from requests to something like `/some/path/*` or `/some/path/*.html` which may be used web applications to uniformly handle resources to be created.

This method checks whether the resource path ends with a `/*` indicating such a star resource.

Parameters:
  `res` - The `Resource` to check whether it is a star resource.
Returns:
  `true` if `res` is to be considered a star resource.
Throws:
  `NullPointerException` - if `res` is `null`.

### isNonExistingResource

public static boolean isNonExistingResource(@NotNull @NotNull Resource res)
Returns `true` if the resource `res` is a non-existing resource.

This method checks the resource type of the resource to match the well-known resource type `sling:nonexisting` of the `NonExistingResource` class defined in the Sling API.

Parameters:
  `res` - The `Resource` to check whether it is a non-existing resource.
Returns:
  `true` if `res` is to be considered a non-existing resource.
Throws:
  `NullPointerException` - if `res` is `null`.

### listChildren

@Deprecated @NotNull public static @NotNull Iterator<Resource> listChildren(@NotNull @NotNull Resource parent)
Deprecated.
since 2.1.0, use `Resource.listChildren()` instead
Returns an `Iterator` of `Resource` objects loaded from the children of the given `Resource`.

This is a convenience method for `ResourceResolver.listChildren(Resource)`.

Parameters:
  `parent` - The `Resource` whose children are requested.
Returns:
  An `Iterator` of `Resource` objects.
Throws:
  `NullPointerException` - If `parent` is `null`.
  `IllegalStateException` - if the resource resolver has already been closed}.
  `SlingException` - If any error occurs acquiring the child resource iterator.
See Also:
  - `ResourceResolver.listChildren(Resource)`

### getValueMap

@NotNull public static @NotNull ValueMap getValueMap(Resource res)
Returns an `ValueMap` object for the given `Resource`. This method calls `Resource.getValueMap()`. If `null` is provided as the resource an empty map is returned as well.

For backward compatibility reasons the map returned is not immutable, but it is not recommend to rely on this behavior.

Parameters:
  `res` - The `Resource` to adapt to the value map.
Returns:
  A value map.

### resourceTypeToPath

@NotNull public static @NotNull String resourceTypeToPath(@NotNull @NotNull String type)
Helper method, which returns the given resource type as returned from the `Resource.getResourceType()` as a relative path.

Parameters:
  `type` - The resource type to be converted into a path
Returns:
  The resource type as a path.
Since:
  2.0.6 (Sling API Bundle 2.0.6)

### getResourceSuperType

@Deprecated @Nullable public static @Nullable String getResourceSuperType(@NotNull @NotNull ResourceResolver resourceResolver, String resourceType)
Deprecated.
Use `ResourceResolver.getParentResourceType(String)`
Returns the super type of the given resource type. This method converts the resource type to a resource path by calling `resourceTypeToPath(String)` and uses the `resourceResolver` to get the corresponding resource. If the resource exists, the `Resource.getResourceSuperType()` method is called.

Parameters:
  `resourceResolver` - The `ResourceResolver` used to access the resource whose path (relative or absolute) is given by the `resourceType` parameter.
  `resourceType` - The resource type whose super type is to be returned. This type is turned into a path by calling the `resourceTypeToPath(String)` method before trying to get the resource through the `resourceResolver`.
Returns:
  the super type of the `resourceType` or `null` if the resource type does not exists or returns `null` for its super type.
Throws:
  `IllegalStateException` - if the resource resolver has already been closed}.
Since:
  2.0.6 (Sling API Bundle 2.0.6)

### findResourceSuperType

@Deprecated @Nullable public static @Nullable String findResourceSuperType(@NotNull @NotNull Resource resource)
Deprecated.
Use `ResourceResolver.getParentResourceType(Resource)`
Returns the super type of the given resource. This method checks first if the resource itself knows its super type by calling `Resource.getResourceSuperType()`. If that returns `null` `getResourceSuperType(ResourceResolver, String)` is invoked with the resource type of the resource.

Parameters:
  `resource` - The resource to return the resource super type for.
Returns:
  the super type of the `resource` or `null` if no super type could be computed.
Throws:
  `IllegalStateException` - if the resource resolver has already been closed}.
Since:
  2.0.6 (Sling API Bundle 2.0.6)

### isA

@Deprecated public static boolean isA(@NotNull @NotNull Resource resource, String resourceType)
Deprecated.
Use `ResourceResolver.isResourceType(Resource, String)`
Check if the resource is of the given type. This method first checks the resource type of the resource, then its super resource type and continues to go up the resource super type hierarchy. 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.

Parameters:
  `resource` - the resource to check
  `resourceType` - the resource type to check the resource against
Returns:
  `false` if `resource` is `null`. Otherwise returns the result of calling `Resource.isResourceType(String)` with the given `resourceType`.
Throws:
  `IllegalStateException` - if the resource resolver has already been closed}.
Since:
  2.0.6 (Sling API Bundle 2.0.6)

### adaptTo

@NotNull public static <T> @NotNull Iterator<T> adaptTo(@NotNull @NotNull Iterator<Resource> iterator, Class<T> type)
Return an iterator for objects of the specified type. A new iterator is returned which tries to adapt the provided resources to the given type (using `Adaptable.adaptTo(Class)`. If a resource in the original iterator is not adaptable to the given class, this object is skipped. This implies that the number of objects returned by the new iterator might be less than the number of resource objects.

Type Parameters:
  `T` - The adapted type
Parameters:
  `iterator` - A resource iterator.
  `type` - The adapted type
Returns:
  An iterator of the adapted objects
Since:
  2.0.6 (Sling API Bundle 2.0.6)

### getOrCreateResource

@NotNull public static @NotNull Resource getOrCreateResource(@NotNull @NotNull ResourceResolver resolver, @NotNull @NotNull String path, String resourceType, String intermediateResourceType, boolean autoCommit) throws PersistenceException
Creates or gets the resource at the given path.

Parameters:
  `resolver` - The resource resolver to use for creation
  `path` - The full path to be created
  `resourceType` - The optional resource type of the final resource to create
  `intermediateResourceType` - THe optional resource type of all intermediate resources
  `autoCommit` - If set to true, a commit is performed after each resource creation.
Returns:
  The resource for the path.
Throws:
  `SlingException` - If an error occurs trying to get/create the resource object from the path.
  `IllegalStateException` - if the resource resolver has already been closed}.
  `PersistenceException` - If a persistence error occurs.
Since:
  2.3.0 (Sling API Bundle 2.4.0)

### getOrCreateResource

@NotNull public static @NotNull Resource getOrCreateResource(@NotNull @NotNull ResourceResolver resolver, @NotNull @NotNull String path, Map<String,Object> resourceProperties, String intermediateResourceType, boolean autoCommit) throws PersistenceException
Creates or gets the resource at the given path. If an exception occurs, it retries the operation up to five times if autoCommit is enabled. In this case, `ResourceResolver.revert()` is called on the resolver before the creation is retried.

Parameters:
  `resolver` - The resource resolver to use for creation
  `path` - The full path to be created
  `resourceProperties` - The optional resource properties of the final resource to create
  `intermediateResourceType` - THe optional resource type of all intermediate resources
  `autoCommit` - If set to true, a commit is performed after each resource creation.
Returns:
  The resource for the path.
Throws:
  `SlingException` - If an error occurs trying to get/create the resource object from the path.
  `IllegalStateException` - if the resource resolver has already been closed}.
  `PersistenceException` - If a persistence error occurs.
Since:
  2.3.0 (Sling API Bundle 2.4.0)

### createUniqueChildName

public static String createUniqueChildName(Resource parent, String name) throws PersistenceException
Create a unique name for a child of the `parent`. Creates a unique name and test if child already exists. If child resource with the same name exists, iterate until a unique one is found.

Parameters:
  `parent` - The parent resource
  `name` - The name of the child resource
Returns:
  a unique non-existing name for child resource for a given `parent`
Throws:
  `PersistenceException` - if it can not find unique name for child resource.
  `NullPointerException` - if `parent` is null
  `IllegalStateException` - if the resource resolver has already been closed}.
Since:
  2.5 (Sling API Bundle 2.7.0)

### unwrap

@NotNull public static @NotNull Resource unwrap(@NotNull @NotNull Resource rsrc)
Unwrap the resource and return the wrapped implementation.

Parameters:
  `rsrc` - The resource to unwrap
Returns:
  The unwrapped resource
Since:
  2.5 (Sling API Bundle 2.7.0)

### getBatchResourceRemover

@NotNull public static @NotNull ResourceUtil.BatchResourceRemover getBatchResourceRemover(int threshold)
Create a batch resource remover. A batch resource remove can be used to delete resources in batches. Once the passed in threshold of deleted resources is reached, an intermediate commit is called on the resource resolver. In addition the batch remover deletes a resource recursively. Once all resources to delete are passed to the remover, a final commit needs to be call on the resource resolver.

Parameters:
  `threshold` - The threshold for the intermediate saves.
Returns:
  A new batch resource remover. Since 2.6