com.google.gerrit.extensions.restapi.RestCollection Maven / Gradle / Ivy
// Copyright (C) 2012 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.gerrit.extensions.restapi;
import com.google.gerrit.extensions.registration.DynamicMap;
/**
* 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 {@link ChildCollection}.
*
* @param
type of the parent resource. For a top level collection this should always be {@link
* TopLevelResource}.
* @param type of resource operated on by each view.
*/
public interface RestCollection {
/**
* 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.
*
* @return view to list the collection.
* @throws ResourceNotFoundException if the collection doesn't support listing.
* @throws AuthException if the collection requires authentication.
* @throws RestApiException if the collection cannot be listed.
*/
RestView
list() throws RestApiException;
/**
* Parse a path component into a resource handle.
*
* @param parent the handle to the collection.
* @param id string identifier supplied by the client. In a URL such as {@code
* /changes/1234/abandon} this string is {@code "1234"}.
* @return 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.
* @throws Exception if the implementation had any errors converting to a resource handle. This
* results in an HTTP 500 Internal Server Error.
*/
R parse(P parent, IdString id) throws ResourceNotFoundException, Exception;
/**
* Get the views that support this collection.
*
*
Within a resource the views are accessed as {@code RESOURCE/plugin~view}.
*
* @return map of views.
*/
DynamicMap> views();
}