// 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.
* <p>
* To build a collection declare a resource, the map in a module, and the
* collection itself accepting the map:
*
* <pre>
* 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;
* }
* }
* </pre>
*
* <p>
* To build a nested collection, implement {@link ChildCollection}.
*
* @param <P> type of the parent resource. For a top level collection this
* should always be {@link TopLevelResource}.
* @param <R> type of resource operated on by each view.
*/
public interface RestCollection<P extends RestResource, R extends RestResource> {
/**
* Create a view to list the contents of the collection.
* <p>
* 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 cannot be listed.
* @throws AuthException if the collection requires authentication.
*/
RestView<P> list() throws ResourceNotFoundException, AuthException;
/**
* 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.
* <p>
* Within a resource the views are accessed as {@code RESOURCE/plugin~view}.
*
* @return map of views.
*/
DynamicMap<RestView<R>> views();
}