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.

In general, page-relative URIs are recommended since they are independent of reverse-proxy URI mappings and mash-up scenarios.

A robust page

A robust page uses page-relative links that are adjusted for path information. URIUtils provides a means to construct these links with the getRelativeUri() API, as shown in the following code example:

<!-- greeting.groovy:  Version 1 -->
<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.

A broken page

The following code illustrates using a simple greeting.gt, which returns an HTML page containing three images.

Notice what occurs when the page is requested under three different scenarios, as shown in the following code example:

<!-- greeting.groovy:  Version 2 -->
<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	URL at which the client attempts to connect
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` (fails)
Context root (`/sample`)	`http://host/sample/greeting.gt`	`http://host/images/absolute.jpg` (fails) `http://host/images/root.jpg` (fails) `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.

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) { ... }

For a complete reference to the URI utilities, view the zero.core.utils.URIUtils Javadoc.