/**
* 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;
}
