All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.gerrit.extensions.restapi.RestCollection Maven / Gradle / Ivy

There is a newer version: 3.10.1
Show newest version
// 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(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy