/** * Returns a new request handler which will forward requests on to the provided collection * resource provider. Incoming requests which are not appropriate for a resource collection or * resource instance will result in a bad request error being returned to the client. * * <p>The provided URI template must match the resource collection itself, not resource instances. * In addition, the URI template must not contain a {@code id} template variable since this will * be implicitly added to the template in order for matching against resource instances. For * example: * * <pre> * CollectionResourceProvider users = ...; * * // This is valid usage: the template matches the resource collection. * RequestHandler handler = newCollection(EQUALS, "/users", users); * * // This is invalid usage: the template matches resource instances. * RequestHandler handler = newCollection(EQUALS, "/users/{userId}", users); * </pre> * * @param mode Indicates how the URI template should be matched against resource instance names. * @param uriTemplate The URI template which should be used for matching against the resource * collection. * @param provider The collection resource provider. * @return A new request handler which will forward requests on to the provided collection * resource provider. * @throws IllegalArgumentException If {@code uriTemplate} contained a template variable called * {@code id}. */ public static RequestHandler newCollection( final RoutingMode mode, final String uriTemplate, final CollectionResourceProvider provider) { // Route requests to the collection/instance using a router. final Router router = new Router(); addCollectionRoutes(router, mode, uriTemplate, provider); return router; }