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>

All Known Implementing Classes:

AccessCollection, AccountsCollection, BranchesCollection, CachesCollection, Capabilities, CapabilitiesCollection, ChangeEdits, ChangeMessages, ChangesCollection, ChildProjectsCollection, Comments, CommitsCollection, ConfigCollection, DashboardsCollection, DraftComments, EmailsCollection, Files, FilesCollection, FilesInCommitCollection, Fixes, GroupsCollection, MembersCollection, PluginsCollection, ProjectsCollection, Reviewers, RevisionReviewers, Revisions, RobotComments, SshKeys, StarredChanges, Stars, SubgroupsCollection, TagsCollection, TasksCollection, TopMenuCollection, Votes

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 and 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 Detail

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.