Package org.apache.sling.api.uri

# Class SlingUriBuilder

java.lang.Object
org.apache.sling.api.uri.SlingUriBuilder

@ProviderType public class SlingUriBuilder extends Object
Builder for immutable `SlingUri`s.

Example:

     SlingUri testUri = SlingUriBuilder.create()
             .setResourcePath("/test/to/path")
             .setSelectors(new String[] { "sel1", "sel2" })
             .setExtension("html")
             .setSuffix("/suffix/path")
             .setQuery("par1=val1&par2=val2")
             .build();

Since:
  1.0.0 (Sling API Bundle 2.23.0)

## Method Summary

Modifier and Type
Method
Description
`@NotNull SlingUriBuilder`
`addQueryParameter(@NotNull String parameterName, @NotNull String value)`
Add a query parameter to the query of the URI.
`@NotNull SlingUriBuilder`
`addSelector(@NotNull String selector)`
Add a selector to the URI.
`@NotNull SlingUri`
`build()`
Builds the immutable SlingUri from this builder.
`static @NotNull SlingUriBuilder`
`create()`
Creates a builder without any URI parameters set.
`static @NotNull SlingUriBuilder`
`createFrom(@NotNull URI uri, @Nullable ResourceResolver resourceResolver)`
Creates a builder from an arbitrary URI.
`static @NotNull SlingUriBuilder`
`createFrom(@NotNull RequestPathInfo requestPathInfo)`
Creates a builder from a RequestPathInfo instance .
`static @NotNull SlingUriBuilder`
`createFrom(@NotNull Resource resource)`
Creates a builder from a resource (only taking the resource path into account).
`static @NotNull SlingUriBuilder`
`createFrom(@NotNull SlingJakartaHttpServletRequest request)`
Creates a builder from a request.
`static @NotNull SlingUriBuilder`
`createFrom(@NotNull SlingUri slingUri)`
Creates a builder from another SlingUri (clone and modify use case).
`static @NotNull SlingUriBuilder`
`createFrom(SlingHttpServletRequest request)`
Deprecated.
Use `createFrom(SlingJakartaHttpServletRequest)` instead.
`@Nullable String`
`getExtension()`
Returns the extension.
`@Nullable String`
`getFragment()`
Returns the fragment.
`@Nullable String`
`getHost()`
Returns the host.
`@Nullable String`
`getPath()`
Returns the joint path of resource path, selectors, extension and suffix.
`@Nullable Map<String,String>`
`getPathParameters()`
Returns the path parameters.
`int`
`getPort()`
Returns the port.
`@Nullable String`
`getQuery()`
Returns the query.
`@Nullable String`
`getResourcePath()`
Returns the resource path.
`@Nullable String`
`getScheme()`
Returns the scheme.
`@Nullable String`
`getSchemeSpecificPart()`
Returns the scheme-specific part of the URI, compare with Javadoc of `URI`.
`@NotNull String[]`
`getSelectors()`
Returns the selectors array.
`@Nullable String`
`getSelectorString()`
Returns the selector string
`@Nullable String`
`getSuffix()`
Returns the suffix part of the URI
`@Nullable Resource`
`getSuffixResource()`
Returns the corresponding suffix resource or null if no resource resolver is available (depends on the create method used in SlingUriBuilder) the URI does not contain a suffix if the suffix resource could not be found
`@Nullable String`
`getUserInfo()`
Returns the user info.
`boolean`
`isAbsolute()`
Returns true the URI is an absolute URI.
`boolean`
`isAbsolutePath()`
Returns true if the URI has an absolute path starting with a slash ('/').
`boolean`
`isOpaque()`
Returns true for opaque URIs like e.g.
`boolean`
`isPath()`
Returns true the URI is either a relative or absolute path (this is the case if scheme and host is empty and the URI path is set)
`boolean`
`isRelativePath()`
Returns true if the URI is a relative path (no scheme and path does not start with '/').
`static @NotNull SlingUriBuilder`
`parse(@NotNull String uriStr, @Nullable ResourceResolver resourceResolver)`
Creates a builder from an arbitrary URI string.
`@NotNull SlingUriBuilder`
`rebaseResourcePath()`
Will rebase the URI based on the underlying resource structure.
`@NotNull SlingUriBuilder`
`removeSchemeAndAuthority()`
Will remove scheme and authority (that is user info, host and port).
`@NotNull SlingUriBuilder`
`removeSelector(@NotNull String selector)`
Remove a selector from the URI.
`@NotNull SlingUriBuilder`
`setExtension(@Nullable String extension)`
Set the extension of the URI.
`@NotNull SlingUriBuilder`
`setFragment(@Nullable String fragment)`
Set the fragment of the URI.
`@NotNull SlingUriBuilder`
`setHost(@Nullable String host)`
Set the host of the URI.
`@NotNull SlingUriBuilder`
`setPath(@Nullable String path)`
Set the path of the URI that contains a resource path and optionally path parameters, selectors, an extension and a suffix.
`@NotNull SlingUriBuilder`
`setPathParameter(@NotNull String key, @NotNull String value)`
Set a path parameter to the URI.
`@NotNull SlingUriBuilder`
`setPathParameters(@NotNull Map<String,String> pathParameters)`
Replaces all path parameters in the URI.
`@NotNull SlingUriBuilder`
`setPort(int port)`
Set the port of the URI.
`@NotNull SlingUriBuilder`
`setQuery(@Nullable String query)`
Set the query of the URI.
`@NotNull SlingUriBuilder`
`setQueryParameters(@NotNull Map<String,String> queryParameters)`
Replace all query parameters of the URL.
`@NotNull SlingUriBuilder`
`setResourcePath(@Nullable String resourcePath)`
Set the resource path of the URI.
`@NotNull SlingUriBuilder`
`setResourceResolver(ResourceResolver resourceResolver)`
Sets the resource resolver (required for `RequestPathInfo.getSuffixResource()`).
`@NotNull SlingUriBuilder`
`setScheme(@Nullable String scheme)`
Set the scheme of the URI.
`@NotNull SlingUriBuilder`
`setSchemeSpecificPart(@Nullable String schemeSpecificPart)`
Set the scheme specific part of the URI.
`@NotNull SlingUriBuilder`
`setSelectors(@Nullable String[] selectors)`
Set the selectors of the URI.
`@NotNull SlingUriBuilder`
`setSuffix(@Nullable String suffix)`
Set the suffix of the URI.
`@NotNull SlingUriBuilder`
`setUserInfo(@Nullable String userInfo)`
Set the user info of the URI.
`String`
`toString()`
Builds the corresponding string URI for this builder.
`@NotNull SlingUriBuilder`
`useSchemeAndAuthority(@NotNull URI uri)`
Will take over scheme and authority (user info, host and port) from provided URI.
`@NotNull SlingUriBuilder`
`useSchemeAndAuthority(@NotNull SlingUri slingUri)`
Will take over scheme and authority (user info, host and port) from provided slingUri.

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

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

## Method Details

### create

@NotNull public static @NotNull SlingUriBuilder create()
Creates a builder without any URI parameters set.

Returns:
  a SlingUriBuilder

### createFrom

@NotNull public static @NotNull SlingUriBuilder createFrom(@NotNull @NotNull SlingUri slingUri)
Creates a builder from another SlingUri (clone and modify use case).

Parameters:
  `slingUri` - the Sling URI to clone
Returns:
  a SlingUriBuilder

### createFrom

@NotNull public static @NotNull SlingUriBuilder createFrom(@NotNull @NotNull Resource resource)
Creates a builder from a resource (only taking the resource path into account).

Parameters:
  `resource` - the resource to take the resource path from
Returns:
  a SlingUriBuilder

### createFrom

@NotNull public static @NotNull SlingUriBuilder createFrom(@NotNull @NotNull RequestPathInfo requestPathInfo)
Creates a builder from a RequestPathInfo instance .

Parameters:
  `requestPathInfo` - the request path info to take resource path, selectors, extension and suffix from.
Returns:
  a SlingUriBuilder

### createFrom

@Deprecated @NotNull public static @NotNull SlingUriBuilder createFrom(@NotNull SlingHttpServletRequest request)
Deprecated.
Use `createFrom(SlingJakartaHttpServletRequest)` instead.
Creates a builder from a request.

Parameters:
  `request` - request to take the URI information from
Returns:
  a SlingUriBuilder

### createFrom

@NotNull public static @NotNull SlingUriBuilder createFrom(@NotNull @NotNull SlingJakartaHttpServletRequest request)
Creates a builder from a request.

Parameters:
  `request` - request to take the URI information from
Returns:
  a SlingUriBuilder
Since:
  1.4.0

### createFrom

@NotNull public static @NotNull SlingUriBuilder createFrom(@NotNull @NotNull URI uri, @Nullable @Nullable ResourceResolver resourceResolver)
Creates a builder from an arbitrary URI.

Parameters:
  `uri` - the uri to transform to a SlingUri
  `resourceResolver` - a resource resolver is needed to decide up to what part the path is the resource path (that decision is only possible by checking against the underlying repository). If null is passed in, the shortest viable resource path is used.
Returns:
  a SlingUriBuilder

### parse

@NotNull public static @NotNull SlingUriBuilder parse(@NotNull @NotNull String uriStr, @Nullable @Nullable ResourceResolver resourceResolver)
Creates a builder from an arbitrary URI string.

Parameters:
  `uriStr` - to uri string to parse
  `resourceResolver` - a resource resolver is needed to decide up to what part the path is the resource path (that decision is only possible by checking against the underlying repository). If null is passed in, the shortest viable resource path is used.
Returns:
  a SlingUriBuilder

### setUserInfo

@NotNull public @NotNull SlingUriBuilder setUserInfo(@Nullable @Nullable String userInfo)
Set the user info of the URI.

Parameters:
  `userInfo` - the user info
Returns:
  the builder for method chaining

### setHost

@NotNull public @NotNull SlingUriBuilder setHost(@Nullable @Nullable String host)
Set the host of the URI.

Parameters:
  `host` - the host
Returns:
  the builder for method chaining

### setPort

@NotNull public @NotNull SlingUriBuilder setPort(int port)
Set the port of the URI.

Parameters:
  `port` - the port
Returns:
  the builder for method chaining

### setPath

@NotNull public @NotNull SlingUriBuilder setPath(@Nullable @Nullable String path)
Set the path of the URI that contains a resource path and optionally path parameters, selectors, an extension and a suffix. To remove an existing path set path to `null`.

Parameters:
  `path` - the path
Returns:
  the builder for method chaining

### rebaseResourcePath

@NotNull public @NotNull SlingUriBuilder rebaseResourcePath()
Will rebase the URI based on the underlying resource structure. Rebasing will potentially adjust the `resourcePath`, `selectors`, `extension` and `suffix` in a way that the path resolves to an existing resource.

A resource resolver is necessary for this operation, hence `setResourceResolver(ResourceResolver)` needs to be called before `rebaseResourcePath()` or a create method that implicitly sets this has to be used.

Returns:
  the builder for method chaining
Throws:
  `IllegalStateException` - if no resource resolver is available

### setResourcePath

@NotNull public @NotNull SlingUriBuilder setResourcePath(@Nullable @Nullable String resourcePath)
Set the resource path of the URI.

Parameters:
  `resourcePath` - the resource path
Returns:
  the builder for method chaining

### setSelectors

@NotNull public @NotNull SlingUriBuilder setSelectors(@Nullable @Nullable String[] selectors)
Set the selectors of the URI. Passing in `null` has the same effect as passing in an empty array.

Parameters:
  `selectors` - the selectors
Returns:
  the builder for method chaining

### addSelector

@NotNull public @NotNull SlingUriBuilder addSelector(@NotNull @NotNull String selector)
Add a selector to the URI.

Parameters:
  `selector` - the selector to add
Returns:
  the builder for method chaining

### removeSelector

@NotNull public @NotNull SlingUriBuilder removeSelector(@NotNull @NotNull String selector)
Remove a selector from the URI.

Parameters:
  `selector` - the selector to remove
Returns:
  the builder for method chaining
Since:
  1.3 (Sling API Bundle 2.25.0)

### setExtension

@NotNull public @NotNull SlingUriBuilder setExtension(@Nullable @Nullable String extension)
Set the extension of the URI.

Parameters:
  `extension` - the extension
Returns:
  the builder for method chaining

### setPathParameter

@NotNull public @NotNull SlingUriBuilder setPathParameter(@NotNull @NotNull String key, @NotNull @NotNull String value)
Set a path parameter to the URI.

Parameters:
  `key` - the path parameter key
  `value` - the path parameter value
Returns:
  the builder for method chaining

### setPathParameters

@NotNull public @NotNull SlingUriBuilder setPathParameters(@NotNull @NotNull Map<String,String> pathParameters)
Replaces all path parameters in the URI.

Parameters:
  `pathParameters` - the path parameters
Returns:
  the builder for method chaining

### setSuffix

@NotNull public @NotNull SlingUriBuilder setSuffix(@Nullable @Nullable String suffix)
Set the suffix of the URI.

Parameters:
  `suffix` - the suffix
Returns:
  the builder for method chaining

### setQuery

@NotNull public @NotNull SlingUriBuilder setQuery(@Nullable @Nullable String query)
Set the query of the URI.

Parameters:
  `query` - the query
Returns:
  the builder for method chaining

### addQueryParameter

@NotNull public @NotNull SlingUriBuilder addQueryParameter(@NotNull @NotNull String parameterName, @NotNull @NotNull String value)
Add a query parameter to the query of the URI. Key and value are URL-encoded before adding the parameter to the query string.

Parameters:
  `parameterName` - the parameter name
  `value` - the parameter value
Returns:
  the builder for method chaining

### setQueryParameters

@NotNull public @NotNull SlingUriBuilder setQueryParameters(@NotNull @NotNull Map<String,String> queryParameters)

Replace all query parameters of the URL. Both keys and values are URL-encoded before adding them to the query string.

For adding multiple query parameters with the same name prefer to use `addQueryParameter(String, String)`.

Parameters:
  `queryParameters` - the map with the query parameters
Returns:
  the builder for method chaining

### setFragment

@NotNull public @NotNull SlingUriBuilder setFragment(@Nullable @Nullable String fragment)
Set the fragment of the URI.

Parameters:
  `fragment` - the fragment
Returns:
  the builder for method chaining

### setScheme

@NotNull public @NotNull SlingUriBuilder setScheme(@Nullable @Nullable String scheme)
Set the scheme of the URI.

Parameters:
  `scheme` - the scheme
Returns:
  the builder for method chaining

### setSchemeSpecificPart

@NotNull public @NotNull SlingUriBuilder setSchemeSpecificPart(@Nullable @Nullable String schemeSpecificPart)
Set the scheme specific part of the URI. Use this for e.g. mail:jon@example.com URIs.

Parameters:
  `schemeSpecificPart` - the scheme specific part
Returns:
  the builder for method chaining

### removeSchemeAndAuthority

@NotNull public @NotNull SlingUriBuilder removeSchemeAndAuthority()
Will remove scheme and authority (that is user info, host and port).

Returns:
  the builder for method chaining

### useSchemeAndAuthority

@NotNull public @NotNull SlingUriBuilder useSchemeAndAuthority(@NotNull @NotNull SlingUri slingUri)
Will take over scheme and authority (user info, host and port) from provided slingUri.

Parameters:
  `slingUri` - the Sling URI
Returns:
  the builder for method chaining

### getResourcePath

@Nullable public @Nullable String getResourcePath()
Returns the resource path.

Returns:
  returns the resource path or null if the URI does not contain a path.

### getSelectorString

@Nullable public @Nullable String getSelectorString()
Returns the selector string

Returns:
  returns the selector string or null if the URI does not contain selector(s) (in line with `RequestPathInfo`)

### getSelectors

@NotNull public @NotNull String[] getSelectors()
Returns the selectors array.

Returns:
  the selectors array (empty if the URI does not contain selector(s), never null)

### getExtension

@Nullable public @Nullable String getExtension()
Returns the extension.

Returns:
  the extension or null if the URI does not contain an extension

### getPathParameters

@Nullable public @Nullable Map<String,String> getPathParameters()
Returns the path parameters.

Returns:
  the path parameters or an empty Map if the URI does not contain any

### getSuffix

@Nullable public @Nullable String getSuffix()
Returns the suffix part of the URI

Returns:
  the suffix string or null if the URI does not contain a suffix

### getSuffixResource

@Nullable public @Nullable Resource getSuffixResource()
Returns the corresponding suffix resource or null if

- no resource resolver is available (depends on the create method used in SlingUriBuilder)
- the URI does not contain a suffix
- if the suffix resource could not be found

Returns:
  the suffix resource if available or null

### getPath

@Nullable public @Nullable String getPath()
Returns the joint path of resource path, selectors, extension and suffix.

Returns:
  the path or null if no path is set

### getSchemeSpecificPart

@Nullable public @Nullable String getSchemeSpecificPart()
Returns the scheme-specific part of the URI, compare with Javadoc of `URI`.

Returns:
  scheme specific part of the URI

### getQuery

@Nullable public @Nullable String getQuery()
Returns the query.

Returns:
  the query part of the URI or null if the URI does not contain a query

### getFragment

@Nullable public @Nullable String getFragment()
Returns the fragment.

Returns:
  the fragment or null if the URI does not contain a fragment

### getScheme

@Nullable public @Nullable String getScheme()
Returns the scheme.

Returns:
  the scheme or null if not set

### getHost

@Nullable public @Nullable String getHost()
Returns the host.

Returns:
  returns the host of the SlingUri or null if not set

### getPort

public int getPort()
Returns the port.

Returns:
  returns the port of the SlingUri or -1 if not set

### getUserInfo

@Nullable public @Nullable String getUserInfo()
Returns the user info.

Returns:
  the user info of the SlingUri or null if not set

### useSchemeAndAuthority

@NotNull public @NotNull SlingUriBuilder useSchemeAndAuthority(@NotNull @NotNull URI uri)
Will take over scheme and authority (user info, host and port) from provided URI.

Parameters:
  `uri` - the URI
Returns:
  the builder for method chaining

### setResourceResolver

@NotNull public @NotNull SlingUriBuilder setResourceResolver(ResourceResolver resourceResolver)
Sets the resource resolver (required for `RequestPathInfo.getSuffixResource()`).

Parameters:
  `resourceResolver` - the resource resolver
Returns:
  the builder for method chaining

### build

@NotNull public @NotNull SlingUri build()
Builds the immutable SlingUri from this builder.

Returns:
  the builder for method chaining

### toString

public String toString()
Builds the corresponding string URI for this builder.

Overrides:
  `toString` in class `Object`
Returns:
  string representation of builder

### isPath

public boolean isPath()
Returns true the URI is either a relative or absolute path (this is the case if scheme and host is empty and the URI path is set)

Returns:
  returns true for path URIs

### isAbsolutePath

public boolean isAbsolutePath()
Returns true if the URI has an absolute path starting with a slash ('/').

Returns:
  true if the URI is an absolute path

### isRelativePath

public boolean isRelativePath()
Returns true if the URI is a relative path (no scheme and path does not start with '/').

Returns:
  true if URI is a relative path

### isAbsolute

public boolean isAbsolute()
Returns true the URI is an absolute URI.

Returns:
  true if the URI is an absolute URI containing a scheme.

### isOpaque

public boolean isOpaque()
Returns true for opaque URIs like e.g. mailto:jon@example.com.

Returns:
  true if the URI is an opaque URI