How to Configure the Path Prefix of a Resource Bundle

Author: Manuel - clerezza.org

Date: November 20, 2008

Table of Contents

1. Introduction

2. Setup the Default Prefix in the Resource Bundle

3. Define a Custom Prefix for a Resource Bundle

4. References

1. Introduction

A resource is annotated with the @Path annotation, which specifies where the resource is found. The path value is after compilation hard to change, but it is maybe for desirable the user of that resource to modifiy that path. Therefore Triaxrs offers the possibility to prepend a path prefix to all resources of a resource bundle. A resource bundle is a bundle that provides a javax.ws.rs.core.Application or individual resources, both are marked with the service property set javax.ws.rs=true.

Triaxrs supports two ways to modify the path prefix of a resource bundle:

• The developer of a resource bundle has the option to define a default path prefix in the bundle manifest.
• The user of the bundle can change/define the path prefix over the Triaxrs Prefix Manager service.

2. Setup the Default Prefix in the Resource Bundle

The default path prefix is defined by the developer of that bundle. The prefix can be defined directly in the bundle manifest using the "Triaxrs-PathPrefix"-header or through the pom.xml in the configuration of the maven-bundle-plugin. Here is an example how the header looks in the bundle manifest:

			Triaxrs-PathPrefix: /myprefix
		

The following is an example how the default path prefix configuration is done in the pom.xml:

			...
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
				<extensions>true</extensions>
				<configuration>
					<instructions>
						<Triaxrs-PathPrefix>/myprefix</Triaxrs-PathPrefix>
					</instructions>
				</configuration>
			</plugin>
			...
		

The following resource in the bundle with the above prefix would be reachable under the path "/myprefix/contact/".

		  package org.example.clerezza.tutorial1;

		  import javax.ws.rs.GET;
		  import javax.ws.rs.Path;
		  import javax.ws.rs.QueryParam;

		  @Path("/contact") // sets the path for this service
		  public class App {

			Person[] persons;
			public App() {
				persons = new Person[3];
				persons[0] = new Person("Jane", "Roe");
				persons[1] = new Person("Richard", "Roe");
				persons[2] = new Person("John", "Doe");
			}

			@GET // this method process GET requests
			public Person getPerson(@QueryParam("id") int id) {
				return persons[id];
			}
		  }
		

3. Define a Custom Prefix for a Resource Bundle

The default path prefix is "hard-coded" in the bundle and is hence for the bundle user hard to change. Therefore Triaxrs provides the Triaxrs Prefix Manager service which gives the user the opportunity to customize path prefixes. When a resource bundle is bound to the org.clerezza.triaxrs.JaxRsHandler service, it will look up if a prefix is defined. For this the Triaxrs Prefix Manager maintains a mapping between a bundles symoblic name and its prefix. The user can modify this mapping over the configuration admin service[1]. This allows that the Triaxrs Prefix Manager can be configured over a configuration user interface like for example Felix's OSGi Management Console.

It is also possible to activate or deactivate the usage of the default and custom prefixes. This can be done by setting the service properties "Triaxrs-UseDefaultPrefix" and "Triaxrs-UseCustomPrefix" of the Triaxrs Prefix Manager. They can be set to true or false. By default prefixes are used.

4. References

[1] OSGi Service Platform, Service Compendium, Release 4, Version 4.1, OSGi Alliance., 2007, chap. 104. , ISBN 978-90-79350-02-5

That's all folks for this time!

Copyright (c) 2008 trialox.org (trialox AG, Switzerland)