SlingUri in Apache Sling: A Developer’s Practical Guide 

If you have worked on a Sling project, you know URLs decide everything—what resource loads, which script runs, and what format is returned. In Apache Sling, this is handled using SlingUri. Many developers casually call these objects slinguri.

They behave like Java Platform Standard Edition API Specification java.net.URI, but with deep understanding of Sling URL parts like selectors and suffix. This guide shows how to use them in real projects without touching fragile URL strings.

What Is SlingUri in Simple Words?

SlingUri is an object that breaks a Sling request URL into meaningful parts. It is not plain text. It understands how Sling reads URLs.

Key idea: Immutable URI, Sling request URL, resource identifier

• Holds path, selectors, extension, suffix, and query separately
• Cannot be edited after creation
• Safer than string manipulation

Think of slinguri as a “smart URL container” made for Sling.

Why Developers Get Into Trouble With String URLs

Real problem

You receive this URL in a servlet:

/content/site/page.print.a4.html/data?x=1

You want JSON instead of HTML. Many developers do this:

url.replace(“.html”, “.json”);

This breaks when:

• There are multiple .html parts
• Selectors change
• Query parameters exist

This is where slinguri save you.

Understanding Sling URL Parts (With Example)

Given URL:

/content/site/page.print.a4.html/data?x=1

SlingUri reads:

Part	Value
Path	content/site/page
Selectors	print.a4
Extension	html
Suffix	/data
Query	x=1

This clarity is what makes slinguri powerful.

Both are immutable. But SlingUri understands Sling routing.

Feature	java.net.URI	SlingUri
Understands selectors	No	Yes
Understands suffix	No	Yes
Built for Sling routing	No	Yes

Real Use Case #1: Change Extension Safely

Goal: Convert .html request into .json

Using adjust()

SlingUri newUri = oldUri.adjust(builder ->

    builder.setExtension(“json”)

);

• Old URI stays unchanged
• New URI is clean
• No string errors

This is a common place where slinguri are used in servlets and filters.

Real Use Case #2: Add a Selector for Print View

Goal: Add .print selector

SlingUri printUri = oldUri.adjust(builder ->

    builder.addSelector(“print”)

);

Now the URL becomes:

/content/site/page.print.html

No manual dot handling. No mistakes.

Real Use Case #3: Build a Sling URL from Scratch

When generating links programmatically, use SlingUriBuilder.

SlingUri uri = new SlingUriBuilder()

    .setPath(“/content/site/page”)

    .addSelector(“preview”)

    .setExtension(“html”)

    .build();

This is much cleaner than:

“/content/site/page.preview.html”

This is why experienced developers prefer slinguri.

What Are Opaque URIs in SlingUri?

Not all SlingUri objects point to Sling content.

Examples:

• mailto:team@example.com
• javascript:alert(‘Hi’)

SlingUri can still hold them safely without expecting Sling path structure.

How Sling Uses These URL Parts for Routing

Sling decides rendering like this:

• Path → which resource to load
• Selector → which script to use
• Extension → response type (html/json/xml)
• Suffix → extra data for processing

Because slinguri separate these parts, routing becomes reliable.

Best Practices Developers Follow

Rebuild, don’t edit

Never change URL text manually.

Use adjust() for small changes

Perfect when modifying existing request URLs.

Use Builder for new URLs

Best for link generation.

Treat SlingUri like a value object

Create new ones when needed.

Common Places You’ll Use SlingUri

• Inside servlets to modify request URLs
• In filters for URL rewriting
• While generating internal links
• While building API response URLs
• Logging structured request data

Why This Matters in Real Projects

In large Sling projects:

• URLs are modified frequently
• Multiple selectors are used
• APIs require format switching (html/json)
• Routing depends on clean URL parsing

Using slinguri prevents subtle bugs that are hard to trace when using string operations.

Conclusion

If you work with Apache Sling, understanding slinguri changes how you handle URLs. Their immutable design, knowledge of selectors and suffix, and safe builder methods remove the risk of manual URL errors. With adjust() and SlingUriBuilder, you can modify or create URLs confidently, keeping your routing, rendering, and link generation clean and reliable.