Dynamic-RS is the first project that allows developers to run REST services dynamically in the OSGi environment. While plain JAX-RS allows you to develop REST services for Java in a standard way, Dynamic-RS allows you to install, update and uninstall JAX-RS REST services at runtime without having to restart the application. Dynamic-RS is robust and was tested against different runtime update scenarios.

Why use JAX-RS dynamically?

Using JAX-RS dynamically in the OSGi environment will allow you to:

• Install, uninstall and update Resource Classes at runtime reliably without affecting the availability of the resources.
• Upgrade Entity Classes at runtime adding to them new properties, modifying existing once, etc.
• Change JAX-RS implementations at runtime (switching from Jersey to RESTEasy for example) without affecting the availability of the published resources.

The problem of using JAX-RS dynamically?

The core JAX-RS specification doesn't handle the dynamicity aspect of REST services, and major implementations don't provide simple means to allow developers to run REST services dynamically neither in plain Java or the OSGi environment.

How Dynamic-RS helps?

Dynamic-RS provides a layer between different JAX-RS implementations and your resources that allows to run you resources dynamically in the OSGi environment with minimal effort.

How Dynamic-RS works?

Dynamic-RS API provides one main interface to developers - JaxrsResourcesProvider. This interface returns the resources to be published. When you have resources that you want to publish, you implement this interface and register it as an OSGi service with specific properties. Dynamic-RS will detect the service, retrieve resources from it, and publish them.

When a service with the same name or the same alias with a higher rank is published, Dynamic-RS will replace it with the existing one. If you want to remove the resources, all you have to do is to deregister the service.

Typically, you will provide a separate bundle which contains resource classes and a Bundle Activator which registers the OSGi service that implements the JaxrsResourcesProvider interface.

Example Application

Here is an example (a Products Resource), an implementation of the JaxrsResourcesProvider interface, and the Bundle Activator which register it as an OSGi service:

@Path("/products/")
public class ProductsResource {
	
	@GET
    @Path("{id}.xml")
    @Produces("application/xml")
	public Response getProduct(@PathParam("id") Integer productId) {
		System.out.println("Product");
		for (Product product : products) {
			if (productId.equals(product.getId())) {
				return Response.ok(product).build();
			}
		}
		
		return Response.status(Response.Status.NOT_FOUND).build();
	}
	
	@GET
    @Path(".xml")
    @Produces("application/xml")
    public Product[] getAllProducts() {
		System.out.println("Products");
    	return products;
    }
	
	
	private Product[] products = new Product[] {
		new Product(1, "Product 1", "Product 1 Description", 100),
		new Product(2, "Product 2", "Product 2 Description", 200),
		new Product(3, "Product 3", "Product 3 Description", 300),
		new Product(4, "Product 4", "Product 4 Description", 400),
		new Product(4, "Product 4", "Product 4 Description", 500)	
	};
	
}

public class ResourcesProvider implements JaxrsResourcesProvider {
	
	//@Override
	public Class[] getResourceClasses() {
		return new Class[] { ProductsResource.class };
	}
	
	//@Override
	public HttpContextFactory getHttpContextFactory() {
		return new DefaultHttpContextFactory();
	}

}

public class Activator implements BundleActivator {
	
	//@Override
	public void start(BundleContext bundleContext) throws Exception {
		bundleContext.registerService(JaxrsResourcesProvider.class.getName(),
				new ResourcesProvider(),
				getResourcesProviderServiceProperties());
	}
	
	//@Override
	public void stop(BundleContext bundleContext) throws Exception {
	}
	
	
	protected Dictionary getResourcesProviderServiceProperties() {
		Dictionary result = new Hashtable();
		result.put(DynamicRsConstants.ALIAS_PROPERTY, "/resources");
		result.put(DynamicRsConstants.PROVIDER_NAME_PROPERTY, "products_resource");
		result.put(DynamicRsConstants.PROVIDER_ID_PROPERTY, "products_resource_2");
		result.put(Constants.SERVICE_RANKING, 2);
		return result;
	}
	
}

The example application contain two versions of the Products Resource bundle. The newer one extends the Product entity adding to it a new property, when installed, you will see that the returned product elements will have an additional child XML element.