Fuse ESB - Developing RESTful Web Services

Overview

One of the main advantages of using the URI context is that it provides access to the base URI of the service and the path segment of the URI for the selected resource. This information can be useful for a number of purposes such as making processing decisions based on the URI or calculating URIs to return as part of the response. For example if the base URI of the request contains a .com extension the service may decide to use US dollars and if the base URI contains a .co.uk extension is may decide to us British Pounds.

The UriInfo interface provides methods for accessing the parts of the URI:

the base URI
the resource path
the full URI

Getting the Base URI

The base URI is the root URI on which the service is published. It does not contain any portion of the URI specified in any of the service's @Path annotations. For example if a service implementing the resource defined in Example 3.5 were published to http://fusesource.org and a request was made on http://fusesource.org/montersforhire/nightstalker?12 the base URI would be http://fusesource.org.

Table 8 describes the methods that return the base URI.

Table 8. Methods for accessing a resource's base URI

Method	Desription
`URI getBaseUri();`	Returns the service's base URI as a `URI` object.
`UriBuilder getBaseUriBuilder();`	Returns the base URI as a `javax.ws.rs.core.UriBuilder` object. The `UriBuilder` class is useful for creating URIs for other resources implemented by the service.

Getting the path

The path portion of the request URI is the portion of the URI that was used to select the current resource. It does not include the base URI, but does include any URI template variable and matrix parameters included in the URI.

The value of the path depends on the resource selected. For example, the paths for the resources defined in Example 47 would be:

rootPath — /monstersforhire/
getterPath — /mostersforhire/nightstalker
The GET request was made on /monstersforhire/nightstalker.
putterPath — /mostersforhire/911
The PUT request was made on /monstersforhire/911.

Example 47. Getting a resource's path

@Path("/monstersforhire/")
public class MonsterService
{
  @Context
  UriInfo rootUri;

  ...

  @GET
  public List<Monster> getMonsters(@Context UriInfo getUri)
  {
    String rootPath = rootUri.getPath();
    ...
  }

  @GET
  @Path("\{type}")
  public Monster getMonster(@PathParam("type") String type,
                            @Context UriInfo getUri)
  {
    String getterPath = getUri.getPath();
    ...
  }

  @PUT
  @Path("\{id}")
  public void addMonster(@Encoded @PathParam("type") String type,
                         @Context UriInfo putUri)
  {
    String putterPath = putUri.getPath();
    ...
  }
  ...
}

Table 9 describes the methods that return the resource path.

Table 9. Methods for accessing a resource's path

Method	Desription
`String getPath();`	Returns the resource's path as a decoded URI.
`String getPath(boolean decode);`	Returns the resource's path. Specifying `false` disables URI decoding.
`List<PathSegment> getPathSegments();`	Returns the decoded path as a list of `javax.ws.rs.core.PathSegment` objects. Each portion of the path, including matrix parameters, is placed into a unique entry in the list. For example the resource path `box/round#tall` would result in a list with three entries: `box`, `round`, and `tall`.
`List<PathSegment> getPathSegments(boolean decode);`	Returns the path as a list of `javax.ws.rs.core.PathSegment` objects. Each portion of the path, including matrix parameters, is placed into a unique entry in the list. Specifying `false` disables URI decoding. For example the resource path `box#tall/round` would result in a list with three entries: `box`, `tall`, and `round`.

Getting the full request URI

Table 10 describes the methods that return the full request URI. You have the option of returning the request URI or the absolute path of the resource. The difference is that the request URI includes the any query parameters appended to the URI and the absolute path does not include the query parameters.

Table 10. Methods for accessing the full request URI

Method	Desription
`URI getRequestUri();`	Returns the complete request URI, including query parameters and matrix parameters, as a `java.net.URI` object.
`UriBuilder getRequestUriBuilder();`	Returns the complete request URI, including query parameters and matrix parameters, as a `javax.ws.rs.UriBuilder` object. The `UriBuilder` class is useful for creating URIs for other resources implemented by the service.
`URI getAbsolutePath();`	Returns the complete request URI, including matrix parameters, as a `java.net.URI` object. The absolute path does not include query parameters.
`UriBuilder getAbsolutePathBuilder();`	Returns the complete request URI, including matrix parameters, as a `javax.ws.rs.UriBuilder` object. The absolute path does not include query parameters.

For a request made using the URI http://fusesource.org/montersforhire/nightstalker?12, the getRequestUri() methods would return http://fusesource.org/montersforhire/nightstalker?12. The getAbsolutePath() method would return http://fusesource.org/montersforhire/nightstalker.

Working with the URI

Overview

Getting the Base URI

Getting the path

Getting the full request URI