Package com.google.gerrit.extensions.restapi

Interface RestCollection<P extends RestResource,R extends RestResource>

Type Parameters:
P - type of the parent resource. For a top level collection this should always be TopLevelResource.
R - type of resource operated on by each view.
All Known Subinterfaces:
ChildCollection<P,C>
public interface RestCollection<P extends RestResource,R extends RestResource>
A collection of resources accessible through a REST API.

To build a collection declare a resource, the map in a module, and the collection itself accepting the map: 

 public class MyResource implements RestResource {
   public static final TypeLiteral<RestView<MyResource>> MY_KIND =
       new TypeLiteral<RestView<MyResource>>() {};
 }

 public class MyModule extends AbstractModule {
   @Override
   protected void configure() {
     DynamicMap.mapOf(binder(), MyResource.MY_KIND);

     get(MyResource.MY_KIND, "action").to(MyAction.class);
   }
 }

 public class MyCollection extends RestCollection<TopLevelResource, MyResource> {
   private final DynamicMap<RestView<MyResource>> views;

   @Inject
   MyCollection(DynamicMap<RestView<MyResource>> views) {
     this.views = views;
   }

   public DynamicMap<RestView<MyResource>> views() {
     return views;
   }
 }

To build a nested collection, implement ChildCollection.

  • Method Summary

    Modifier and Type
    Method
    Description
    RestView<P>
    list()
    Create a view to list the contents of the collection.
    R
    parse(P parent, IdString id)
    Parse a path component into a resource handle.
    DynamicMap<RestView<R>>
    views()
    Get the views that support this collection.

  • Method Details

    • list

      RestView<P> list() throws RestApiException
      Create a view to list the contents of the collection.

      The returned view should accept the parent type to scope the search, and may want to take a "q" parameter option to narrow the results.

      Returns:
      view to list the collection.
      Throws:
      ResourceNotFoundException - if the collection doesn't support listing.
      AuthException - if the collection requires authentication.
      RestApiException - if the collection cannot be listed.

    • parse

      R parse(P parent, IdString id) throws ResourceNotFoundException, Exception
      Parse a path component into a resource handle.
      Parameters:
      parent - the handle to the collection.
      id - string identifier supplied by the client. In a URL such as /changes/1234/abandon this string is "1234".
      Returns:
      a resource handle for the identified object.
      Throws:
      ResourceNotFoundException - the object does not exist, or the caller is not permitted to know if the resource exists.
      Exception - if the implementation had any errors converting to a resource handle. This results in an HTTP 500 Internal Server Error.

    • views

      DynamicMap<RestView<R>> views()
      Get the views that support this collection.

      Within a resource the views are accessed as RESOURCE/plugin~view.

      Returns:
      map of views.