If you work with Apache Sling, you have probably encountered the ResourceResolver and its configuration rules.In short, the ResourceResolver is the part of Sling that resolves incoming requests to actual or virtualresources. For example, if a request for/foo/bar is coming in the resolver will resolve that to acorresponding node in the JCR. However, sometimes it is not desireable to expose the internal structure of therepository or the required external structure cannot be represented using the JCR. In that case the resolvercan be customized by installing resolver rules. Resolver rules can be modified via the OSGI configurationeditor or the OSGI ConfigurationAdmin.

Each rule consists of three parts. I’ll call them theinternal path, theoperator, and theexternal path.The syntax is always like this:

<internal path>   <operator>   <external path>

In order to understand whatinternal path andexternal path mean, we need to discuss theoperator first.However, in order to understand the operators, we’ll have to take a quick look at the two fundamental operationsthe resolver performs:resource resolution and theresource mapping.

Resource resolution, as outlined in the introduction, is the process of resolving an incoming request to aresource that Sling can provide, usually a node in the JCR. It’s important to note that the incoming request’spath doesn’t need to correspond to anything in the JCR.

In order to specify a rule that should be applied to the request URI during resource resolution, you wouldspecify a resolver rule using the> operator. For example, to map all requests for/foo to/content/bar in the JCR, you would write the following:

/content/bar>/foo

With this example it becomes obvious whatinternal path andexternal path stand for. In case of a resolverrule,internal path is the path the matching external path is replace with. And in order for resolver rulesto be really useful and scare of the faint of heart, they support regular expressions. So, you can utilizecharacter and matching groups and references:

/content/$1/$2$3>/([a-zA-Z]{2})/(en|fr|de)(.*)

This resolves requests for/us/en/homepage.html to/content/us/en/homepage.html and/ca/fr/foobar.htmlto/content/ca/fr/foobar.html. Neat.

Resource mapping can be thought of as the opposite of resource resolution. Let’s assume the following resolverrule:

/content/bar>/foo

For incoming requests you are covered, clients will only see/foo. However, in the rendered pages, referencesto/content/bar will stills how up as such. So in order to “hide” this path, we need tomap it to anexternal path. This is where the second operator come in. You can specify a map rule using the< operator.For example, to replace/content/bar with/foo, you’d specify the following rule:

/content/bar</foo

Notice how the order of the operands is unchanged, which makes these rules somewhat confusing to work with.Of course, you can use regular expressions to make your rules more powerful and more confusing to simpler minds:

/content/ca/(en|fr)</ohcanada/$1

Again, the order of the operands is important. And in this case, notice how the regular expressions have“switched” side. The matchers are on the left hand, the refrences on the right hand side. Once applied toa path, for example/content/ca/en/homepage, the mapping rule will transform it into/ohcanada/en/homepage.Please note that mapping rules are not magically applied. You need to either callresourceResolver.map() foryour path, or use anoutput rewriting pipeline.

The flexibility of specifying resolver and mapper rules separately, is not needed. In most cases you’d wantthe resolver rules to be reflected in the mapper rules and vice versa. This can be acchieved with the:operator:

/content/bar:/foo

This results in both a mapper and a resolver rule. However, regular expression usage here is limited.

Now, let’s discuss one last aspect, that I’ve been silently ignoring so far. How does Sling behave if thereare multiple rules? First, Sling orders all rules by the number of regular expression groups it contains.(I haven’t found any reference to this in the Sling docs, this is knowledge earned through sweat, blood, andmethodical head banging!)The more groups, the higher the priority of the group. For each incoming request, Sling will try to matchit against all rules in descending order of their priority. First rule that matches, wins. The followingrules for example, have different priorities:

/content/foo/$1>/(pie|cake)/content/bar/$1/$2>/(apples|oranges)/(.*)

The first rule has a single group whereas the second group has two groups. During the resource resolutionprocess, the second rule would always be matchedbefore the first rule.

Once understood, resolver and mapper rules offer a versatile and flexible tool for masking content structuresor offering new external URLs for services. However, the road to understand them, is, at least for me,a stony if not rocky one. I hope this post will help others to understand and implement them.