From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Fri, 15 Jun 2007 11:32:48 -0400

The @SubResources[1] annotation allows a resource class to statically
declare a subresource, e.g.:

@UriTemplate("widgets")
@SubResources({Widget.class})
public class WidgetList {
   ...
}

@UriTemplate("{id}")
public class Widget {
   ...
}

Where the Widget resource class is identified by the relative URI
widgets/xxx where xxx is the value of the {id} parameter.

An alternative, dynamic mechanism is also supported, e.g.:

@UriTemplate("widgets")
@SubResources({Widget.class})
public class WidgetList {

   @UriTemplate("{id}")
   public Widget findWidget(@UriParam("id") String id) {
     ...
   }

   ...
}

In this case the findWidget method returns an instance of class that
extends Widget and the runtime then calls the appropriate annotated
method on the returned instance.

The only real advantage of @SubResources is that there's no need to
instantiate the annotated class (WidgetList) in order to find any
subresources. However, @SubResources introduces a problem of how to
identify those resource classes that should be published at the root
context vs those which should only be accessible as subresources. On
balance we don't think that @SubResources is sufficiently useful to
justify keeping it and we propose to remove it from the API.

Thoughts, comments ?
Marc.

[1] https://jsr311.dev.java.net/sketches/sketch3/javax/ws/rs/
SubResources.html

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.