Implement new /changes/{id}/action style REST API

All existing JSON APIs are converted to this new style.

/changes/{id} parses the id field from a JSON response from a prior
response and uses that to uniquely identify a change and verify the
caller can see it. If the user requests only /changes/{id}/ then the
data is returned as a single JSON object.

This commit also gives full remote control of plugins using the
/plugins/ namespace:

  PUT /plugins/{name}    (JAR as request body)
  POST /plugins/{name}   (JSON object {url:"https://..."})
  DELETE /plugins/{name}
  GET /plugins/{name}/gerrit~status
  POST /plugins/{name}/gerrit~reload
  POST /plugins/{name}/gerrit~enable
  POST /plugins/{name}/gerrit~disable

The commit provides some project admin commands:

  GET /projects/{name}/description
  PUT /projects/{name}/description

  GET /projects/{name}/parent
  PUT /projects/{name}/parent

Project dashboards have moved:

  GET /projects/{name}/dashboards
  GET /projects/{name}/dashboards/{id}
  GET /projects/{name}/dashboards/default

To access project names containing /, the name must be encoded with
URL encoding, translating / to %2F.

Change-Id: I6a38902ee473003ec637758b7c911f926a2e948a

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/AcceptsCreate.java

@@ -0,0 +1,34 @@
+// 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;
+
+/**
+ * Optional interface for {@link RestCollection}.
+ * <p>
+ * Collections that implement this interface can accept a {@code PUT} or
+ * {@code POST} when the parse method throws {@link ResourceNotFoundException}.
+ */
+public interface AcceptsCreate<P extends RestResource> {
+  /**
+   * Handle creation of a child resource.
+   *
+   * @param parent parent collection handle.
+   * @param id id of the resource being created.
+   * @return a view to perform the creation. The create method must embed the id
+   *         into the newly returned view object, as it will not be passed.
+   * @throws RestApiException the view cannot be constructed.
+   */
+  <I> RestModifyView<P, I> create(P parent, String id) throws RestApiException;
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/AuthException.java

@@ -0,0 +1,25 @@
+// 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;
+
+/** Caller cannot perform the request operation (HTTP 403 Forbidden). */
+public class AuthException extends RestApiException {
+  private static final long serialVersionUID = 1L;
+
+  /** @param msg message to return to the client. */
+  public AuthException(String msg) {
+    super(msg);
+  }
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/BadRequestException.java

@@ -0,0 +1,25 @@
+// 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;
+
+/** Request could not be parsed as sent (HTTP 400 Bad Request). */
+public class BadRequestException extends RestApiException {
+  private static final long serialVersionUID = 1L;
+
+  /** @param msg error text for client describing how request is bad. */
+  public BadRequestException(String msg) {
+    super(msg);
+  }
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/BinaryResult.java

@@ -0,0 +1,174 @@
+// 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 java.io.Closeable;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.UnsupportedEncodingException;
+
+/**
+ * Wrapper around a non-JSON result from a {@link RestView}.
+ * <p>
+ * Views may return this type to signal they want the server glue to write raw
+ * data to the client, instead of attempting automatic conversion to JSON. The
+ * create form is overloaded to handle plain text from a String, or binary data
+ * from a {@code byte[]} or {@code InputSteam}.
+ */
+public abstract class BinaryResult implements Closeable {
+  /** Default MIME type for unknown binary data. */
+  static final String OCTET_STREAM = "application/octet-stream";
+
+  /** Produce a UTF-8 encoded result from a string. */
+  public static BinaryResult create(String data) {
+    try {
+      return create(data.getBytes("UTF-8"))
+        .setContentType("text/plain")
+        .setCharacterEncoding("UTF-8");
+    } catch (UnsupportedEncodingException e) {
+      throw new RuntimeException("JVM does not support UTF-8", e);
+    }
+  }
+
+  /** Produce an {@code application/octet-stream} result from a byte array. */
+  public static BinaryResult create(byte[] data) {
+    return new Array(data);
+  }
+
+  /**
+   * Produce an {@code application/octet-stream} of unknown length by copying
+   * the InputStream until EOF. The server glue will automatically close this
+   * stream when copying is complete.
+   */
+  public static BinaryResult create(InputStream data) {
+    return new Stream(data);
+  }
+
+  private String contentType = OCTET_STREAM;
+  private String characterEncoding;
+  private long contentLength = -1;
+  private boolean gzip = true;
+
+  /** @return the MIME type of the result, for HTTP clients. */
+  public String getContentType() {
+    String enc = getCharacterEncoding();
+    if (enc != null) {
+      return contentType + "; charset=" + enc;
+    }
+    return contentType;
+  }
+
+  /** Set the MIME type of the result, and return {@code this}. */
+  public BinaryResult setContentType(String contentType) {
+    this.contentType = contentType != null ? contentType : OCTET_STREAM;
+    return this;
+  }
+
+  /** Get the character encoding; null if not known. */
+  public String getCharacterEncoding() {
+    return characterEncoding;
+  }
+
+  /** Set the character set used to encode text data and return {@code this}. */
+  public BinaryResult setCharacterEncoding(String encoding) {
+    characterEncoding = encoding;
+    return this;
+  }
+
+  /** @return length in bytes of the result; -1 if not known. */
+  public long getContentLength() {
+    return contentLength;
+  }
+
+  /** Set the content length of the result; -1 if not known. */
+  public BinaryResult setContentLength(long len) {
+    this.contentLength = len;
+    return this;
+  }
+
+  /** @return true if this result can be gzip compressed to clients. */
+  public boolean canGzip() {
+    return gzip;
+  }
+
+  /** Disable gzip compression for already compressed responses. */
+  public BinaryResult disableGzip() {
+    this.gzip = false;
+    return this;
+  }
+
+  /**
+   * Write or copy the result onto the specified output stream.
+   *
+   * @param os stream to write result data onto. This stream will be closed by
+   *        the caller after this method returns.
+   * @throws IOException if the data cannot be produced, or the OutputStream
+   *         {@code os} throws any IOException during a write or flush call.
+   */
+  public abstract void writeTo(OutputStream os) throws IOException;
+
+  /** Close the result and release any resources it holds. */
+  public void close() throws IOException {
+  }
+
+  @Override
+  public String toString() {
+    if (getContentLength() >= 0) {
+      return String.format(
+          "BinaryResult[Content-Type: %s, Content-Length: %d]",
+          getContentType(), getContentLength());
+    }
+    return String.format(
+        "BinaryResult[Content-Type: %s, Content-Length: unknown]",
+        getContentType());
+  }
+
+  private static class Array extends BinaryResult {
+    private final byte[] data;
+
+    Array(byte[] data) {
+      this.data = data;
+      setContentLength(data.length);
+    }
+
+    @Override
+    public void writeTo(OutputStream os) throws IOException {
+      os.write(data);
+    }
+  }
+
+  private static class Stream extends BinaryResult {
+    private final InputStream src;
+
+    Stream(InputStream src) {
+      this.src = src;
+    }
+
+    @Override
+    public void writeTo(OutputStream dst) throws IOException {
+      byte[] tmp = new byte[4096];
+      int n;
+      while (0 < (n = src.read(tmp))) {
+        dst.write(tmp, 0, n);
+      }
+    }
+
+    @Override
+    public void close() throws IOException {
+      src.close();
+    }
+  }
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/ChildCollection.java

@@ -0,0 +1,26 @@
+// 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;
+
+
+/**
+ * Nested collection of {@link RestResource}s below a parent.
+ *
+ * @param <P> type of the parent resource.
+ * @param <C> type of resource operated on by each view.
+ */
+public interface ChildCollection<P extends RestResource, C extends RestResource>
+    extends RestView<P>, RestCollection<P, C> {
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/DefaultInput.java

@@ -0,0 +1,27 @@
+// 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 static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/** Applied to a String field to indicate the default input parameter. */
+@Target({ElementType.FIELD})
+@Retention(RUNTIME)
+public @interface DefaultInput {
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/PutInput.java

@@ -0,0 +1,26 @@
+// 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 java.io.IOException;
+import java.io.InputStream;
+
+
+/** Raw data stream supplied by the body of a PUT. */
+public interface PutInput {
+  String getContentType();
+  long getContentLength();
+  InputStream getInputStream() throws IOException;
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/ResourceConflictException.java

@@ -0,0 +1,32 @@
+// 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;
+
+/**
+ * Resource state does not permit requested operation (HTTP 409 Conflict).
+ * <p>
+ * {@link RestModifyView} implementations may fail with this exception when the
+ * named resource does not permit the modification to take place at this time.
+ * An example use is trying to abandon a change that is already merged. The
+ * change cannot be abandoned once merged so an operation would throw.
+ */
+public class ResourceConflictException extends RestApiException {
+  private static final long serialVersionUID = 1L;
+
+  /** @param msg message to return to the client describing the error. */
+  public ResourceConflictException(String msg) {
+    super(msg);
+  }
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/ResourceNotFoundException.java

@@ -0,0 +1,29 @@
+// 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;
+
+/** Named resource does not exist (HTTP 404 Not Found). */
+public class ResourceNotFoundException extends RestApiException {
+  private static final long serialVersionUID = 1L;
+
+  /** Requested resource is not found, failing portion not specified. */
+  public ResourceNotFoundException() {
+  }
+
+  /** @param id portion of the resource URI that does not exist. */
+  public ResourceNotFoundException(String id) {
+    super(id);
+  }
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/RestApiException.java

@@ -0,0 +1,31 @@
+// 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;
+
+/** Root exception type for JSON API failures. */
+public abstract class RestApiException extends Exception {
+  private static final long serialVersionUID = 1L;
+
+  public RestApiException() {
+  }
+
+  public RestApiException(String msg) {
+    super(msg);
+  }
+
+  public RestApiException(String msg, Throwable cause) {
+    super(msg, cause);
+  }
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/RestApiModule.java

@@ -0,0 +1,178 @@
+// 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.annotations.Export;
+import com.google.gerrit.extensions.annotations.Exports;
+import com.google.inject.AbstractModule;
+import com.google.inject.Provider;
+import com.google.inject.TypeLiteral;
+import com.google.inject.binder.LinkedBindingBuilder;
+import com.google.inject.binder.ScopedBindingBuilder;
+
+/** Guice DSL for binding {@link RestView} implementations. */
+public abstract class RestApiModule extends AbstractModule {
+  protected static final String GET = "GET";
+  protected static final String PUT = "PUT";
+  protected static final String DELETE = "DELETE";
+  protected static final String POST = "POST";
+
+  protected <R extends RestResource>
+  ReadViewBinder<R> get(TypeLiteral<RestView<R>> viewType) {
+    return new ReadViewBinder<R>(view(viewType, GET, "/"));
+  }
+
+  protected <R extends RestResource>
+  ModifyViewBinder<R> put(TypeLiteral<RestView<R>> viewType) {
+    return new ModifyViewBinder<R>(view(viewType, PUT, "/"));
+  }
+
+  protected <R extends RestResource>
+  ModifyViewBinder<R> post(TypeLiteral<RestView<R>> viewType) {
+    return new ModifyViewBinder<R>(view(viewType, POST, "/"));
+  }
+
+  protected <R extends RestResource>
+  ModifyViewBinder<R> delete(TypeLiteral<RestView<R>> viewType) {
+    return new ModifyViewBinder<R>(view(viewType, DELETE, "/"));
+  }
+
+  protected <R extends RestResource>
+  ReadViewBinder<R> get(TypeLiteral<RestView<R>> viewType, String name) {
+    return new ReadViewBinder<R>(view(viewType, GET, name));
+  }
+
+  protected <R extends RestResource>
+  ModifyViewBinder<R> put(TypeLiteral<RestView<R>> viewType, String name) {
+    return new ModifyViewBinder<R>(view(viewType, PUT, name));
+  }
+
+  protected <R extends RestResource>
+  ModifyViewBinder<R> post(TypeLiteral<RestView<R>> viewType, String name) {
+    return new ModifyViewBinder<R>(view(viewType, POST, name));
+  }
+
+  protected <R extends RestResource>
+  ModifyViewBinder<R> delete(TypeLiteral<RestView<R>> viewType, String name) {
+    return new ModifyViewBinder<R>(view(viewType, DELETE, name));
+  }
+
+  protected <P extends RestResource>
+  ChildCollectionBinder<P> child(TypeLiteral<RestView<P>> type, String name) {
+    return new ChildCollectionBinder<P>(view(type, GET, name));
+  }
+
+  protected <R extends RestResource>
+  LinkedBindingBuilder<RestView<R>> view(
+      TypeLiteral<RestView<R>> viewType,
+      String method,
+      String name) {
+    return bind(viewType).annotatedWith(export(method, name));
+  }
+
+  private static Export export(String method, String name) {
+    if (name.length() > 1 && name.startsWith("/")) {
+      // Views may be bound as "/" to mean the resource itself, or
+      // as "status" as in "/type/{id}/status". Don't bind "/status"
+      // if the caller asked for that, bind what the server expects.
+      name = name.substring(1);
+    }
+    return Exports.named(method + "." + name);
+  }
+
+  public static class ReadViewBinder<P extends RestResource> {
+    private final LinkedBindingBuilder<RestView<P>> binder;
+
+    private ReadViewBinder(LinkedBindingBuilder<RestView<P>> binder) {
+      this.binder = binder;
+    }
+
+    public <T extends RestReadView<P>>
+    ScopedBindingBuilder to(Class<T> impl) {
+      return binder.to(impl);
+    }
+
+    public <T extends RestReadView<P>>
+    void toInstance(T impl) {
+      binder.toInstance(impl);
+    }
+
+    public <T extends RestReadView<P>>
+    ScopedBindingBuilder toProvider(Class<? extends Provider<? extends T>> providerType) {
+      return binder.toProvider(providerType);
+    }
+
+    public <T extends RestReadView<P>>
+    ScopedBindingBuilder toProvider(Provider<? extends T> provider) {
+      return binder.toProvider(provider);
+    }
+  }
+
+  public static class ModifyViewBinder<P extends RestResource> {
+    private final LinkedBindingBuilder<RestView<P>> binder;
+
+    private ModifyViewBinder(LinkedBindingBuilder<RestView<P>> binder) {
+      this.binder = binder;
+    }
+
+    public <T extends RestModifyView<P, ?>>
+    ScopedBindingBuilder to(Class<T> impl) {
+      return binder.to(impl);
+    }
+
+    public <T extends RestModifyView<P, ?>>
+    void toInstance(T impl) {
+      binder.toInstance(impl);
+    }
+
+    public <T extends RestModifyView<P, ?>>
+    ScopedBindingBuilder toProvider(Class<? extends Provider<? extends T>> providerType) {
+      return binder.toProvider(providerType);
+    }
+
+    public <T extends RestModifyView<P, ?>>
+    ScopedBindingBuilder toProvider(Provider<? extends T> provider) {
+      return binder.toProvider(provider);
+    }
+  }
+
+  public static class ChildCollectionBinder<P extends RestResource> {
+    private final LinkedBindingBuilder<RestView<P>> binder;
+
+    private ChildCollectionBinder(LinkedBindingBuilder<RestView<P>> binder) {
+      this.binder = binder;
+    }
+
+    public <C extends RestResource, T extends ChildCollection<P, C>>
+    ScopedBindingBuilder to(Class<T> impl) {
+      return binder.to(impl);
+    }
+
+    public <C extends RestResource, T extends ChildCollection<P, C>>
+    void toInstance(T impl) {
+      binder.toInstance(impl);
+    }
+
+    public <C extends RestResource, T extends ChildCollection<P, C>>
+    ScopedBindingBuilder toProvider(Class<? extends Provider<? extends T>> providerType) {
+      return binder.toProvider(providerType);
+    }
+
+    public <C extends RestResource, T extends ChildCollection<P, C>>
+    ScopedBindingBuilder toProvider(Provider<? extends T> provider) {
+      return binder.toProvider(provider);
+    }
+  }
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/RestCollection.java

@@ -0,0 +1,95 @@
+// 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&lt;RestView&lt;MyResource&gt;&gt; MY_KIND =
+ *       new TypeLiteral&lt;RestView&lt;MyResource&gt;&gt;() {};
+ * }
+ *
+ * public class MyModule extends AbstractModule {
+ *   &#064;Override
+ *   protected void configure() {
+ *     DynamicMap.mapOf(binder(), MyResource.MY_KIND);
+ *
+ *     get(MyResource.MY_KIND, &quot;action&quot;).to(MyAction.class);
+ *   }
+ * }
+ *
+ * public class MyCollection extends RestCollection&lt;TopLevelResource, MyResource&gt; {
+ *   private final DynamicMap&lt;RestView&lt;MyResource&gt;&gt; views;
+ *
+ *   &#064;Inject
+ *   MyCollection(DynamicMap&lt;RestView&lt;MyResource&gt;&gt; views) {
+ *     this.views = views;
+ *   }
+ *
+ *   public DynamicMap&lt;RestView&lt;MyResource&gt;&gt; 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.
+   */
+  RestView<P> list() throws ResourceNotFoundException;
+
+  /**
+   * 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, String 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();
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/RestModifyView.java

@@ -0,0 +1,53 @@
+// 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;
+
+/**
+ * RestView that supports accepting input and changing a resource.
+ * <p>
+ * The input must be supplied as JSON as the body of the HTTP request. Modify
+ * views can be invoked by any HTTP method that is not {@code GET}, which
+ * includes {@code POST}, {@code PUT}, {@code DELETE}.
+ *
+ * @param <R> type of the resource the view modifies.
+ * @param <I> type of input the JSON parser will parse the input into.
+ */
+public interface RestModifyView<R extends RestResource, I> extends RestView<R> {
+  /**
+   * @return Java class object defining the input type. The JSON parser will
+   *         parse the supplied request body into a new instance of this class
+   *         before passing it to apply.
+   */
+  Class<I> inputType();
+
+  /**
+   * Process the view operation by altering the resource.
+   *
+   * @param resource resource to modify.
+   * @param input input after parsing from request.
+   * @return result to return to the client. Use {@link BinaryResult} to avoid
+   *         automatic conversion to JSON.
+   * @throws AuthException the client is not permitted to access this view.
+   * @throws BadRequestException the request was incorrectly specified and
+   *         cannot be handled by this view.
+   * @throws ResourceConflictException the resource state does not permit this
+   *         view to make the changes at this time.
+   * @throws Exception the implementation of the view failed. The exception will
+   *         be logged and HTTP 500 Internal Server Error will be returned to
+   *         the client.
+   */
+  Object apply(R resource, I input) throws AuthException, BadRequestException,
+      ResourceConflictException, Exception;
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/RestReadView.java

@@ -0,0 +1,40 @@
+// 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;
+
+/**
+ * RestView to read a resource without modification.
+ *
+ * @param <R> type of resource the view reads.
+ */
+public interface RestReadView<R extends RestResource> extends RestView<R> {
+  /**
+   * Process the view operation by reading from the resource.
+   *
+   * @param resource resource to modify.
+   * @return result to return to the client. Use {@link BinaryResult} to avoid
+   *         automatic conversion to JSON.
+   * @throws AuthException the client is not permitted to access this view.
+   * @throws BadRequestException the request was incorrectly specified and
+   *         cannot be handled by this view.
+   * @throws ResourceConflictException the resource state does not permit this
+   *         view to make the changes at this time.
+   * @throws Exception the implementation of the view failed. The exception will
+   *         be logged and HTTP 500 Internal Server Error will be returned to
+   *         the client.
+   */
+  Object apply(R resource) throws AuthException, BadRequestException,
+      ResourceConflictException, Exception;
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/RestResource.java

@@ -0,0 +1,24 @@
+// 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;
+
+/**
+ * Generic resource handle defining arguments to views.
+ * <p>
+ * Resource handle returned by {@link RestCollection} and passed to a
+ * {@link RestView} such as {@link RestReadView} or {@link RestModifyView}.
+ */
+public interface RestResource {
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/RestView.java

@@ -0,0 +1,22 @@
+// 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;
+
+/**
+ * Any type of view, see {@link RestReadView} for reads, {@link RestModifyView}
+ * for updates, and {@link RestCollection} for nested collections.
+ */
+public interface RestView<R extends RestResource> {
+}

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/restapi/TopLevelResource.java

@@ -0,0 +1,23 @@
+// Copyright (C) 2012 The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (thte "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;
+
+/** Special marker resource naming the top-level of a REST space. */
+public class TopLevelResource implements RestResource {
+  public static final TopLevelResource INSTANCE = new TopLevelResource();
+
+  private TopLevelResource() {
+  }
+}