URIUtils APIs

URIUtils is a set of APIs for constructing relative and absolute URIs within an IBM® WebSphere® sMash application. These APIs are helpful when constructing URIs for many purposes, including hyperlinks, images, and CSS links.

Why page-relative URIs are recommended

In general, page-relative URIs are recommended since they are independent of reverse-proxy URI mappings and mash-up scenarios. However, one must take care in constructing these URIs.

A "broken" page

Consider a simple illustration with greeting.gt, which returns an HTML page containing three images:

<!-- greeting.groovy:  Version 1 -->
<html><body>
Hello world.
<img src="http://host/images/absolute.jpg">
<img src="/images/root.jpg">
<img src="images/page.jpg">
</body></html>

Now look at what happens when the page is requested under three different scenarios:

Scenario	Client request	Client tries to access images at...
No context root; exact request	`http://host/greeting.gt`	`http://host/images/absolute.jpg` `http://host/images/root.jpg` `http://host/images/page.jpg`
No context root; request with path info	`http://host/greeting.gt/more`	`http://host/images/absolute.jpg` `http://host/images/root.jpg` `http://host/greeting.gt/images/page.jpg`
Context root (`/sample`)	`http://host/sample/greeting.gt`	`http://host/images/absolute.jpg` `http://host/images/root.jpg` `http://host/sample/images/page.jpg`

The first scenario works fine, but the other two scenarios fail with "broken" image references. In the second scenario, the page-relative link (page.jpg) fails because the user agent resolves it with the request URI, including path info. In the final scenario, the absolute URI (absolute.jpg) and root-relative URI (root.jpg) fail because they are sensitive to changes in deployment.

A robust page

A more robust page will be one that uses page-relative links that are adjusted for path info. URIUtils provides a means to construct these links with the getRelativeUri() API:

<!-- greeting.groovy:  Version 2 -->
<html><body>
Hello world.
<img src="<%= getRelativeUri("/images/absolute.jpg") %>">
<img src="<%= getRelativeUri("/images/root.jpg") %>">
<img src="<%= getRelativeUri("images/page.jpg") %>">
</body></html>

Note that the leading slash in the argument to getRelativeUri() is significant:

With a leading slash, the argument is considered relative to the application root without WebSphere sMash's context root. You could think of this as specifying a URI starting from the public folder of your application.
Without a leading slash, the argument is relative to the calling script.

API reference

URIUtils includes the following utility APIs:

public static String getRelativeUri(String path) { ... }
public static String getRelativeUri(String path, Map<String,String> queryParms) { ... }
public static String getRelativeUri(String path, Map<String,String> queryParms, String fragment) { ... }
public static String getAbsoluteUri(String path) { ... }
public static String getAbsoluteUri(String path, Map<String,String> queryParms) { ... }
public static String getAbsoluteUri(String path, Map<String,String> queryParms, String fragment) { ... }
public static String getRequestedUri(boolean includeQueryString) { ... }

Usage details may be found in the Javadoc.