Use IdString to wrap encoded strings in REST API calls

Clients supply encoded strings as the id portion of REST API
paths. These strings need to be decoded within the view code
as some encodings are specially handled. Try to prevent misuse
by wrapping strings in a type-safe IdString wrapper that forces
developers to decode with ".get()" before using.

The raw string can be obtained with ".encoded()", an obvious
hint that the return value will still be URL encoded. This is
used in only a handful of locations where special parsing must
be performed.

Change-Id: Ied5747d1fe8cc0f2dc24017f7aacc2fcab69a37c

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

@@ -30,5 +30,5 @@ public interface AcceptsCreate<P extends RestResource> {
    *         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;
+  <I> RestModifyView<P, I> create(P parent, IdString id) throws RestApiException;
 }

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

@@ -0,0 +1,68 @@
+// Copyright (C) 2013 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 identifier split out from a URL.
+ * <p>
+ * Identifiers are URL encoded and usually need to be decoded.
+ */
+public class IdString {
+  /** Construct an identifier from an already encoded string. */
+  public static IdString fromUrl(String id) {
+    return new IdString(id);
+  }
+
+  private final String urlEncoded;
+
+  private IdString(String s) {
+    urlEncoded = s;
+  }
+
+  /** @return the decoded value of the string. */
+  public String get() {
+    return Url.decode(urlEncoded);
+  }
+
+  /** @return true if the string is the empty string. */
+  public boolean isEmpty() {
+    return urlEncoded.isEmpty();
+  }
+
+  /** @return the original URL encoding supplied by the client. */
+  public String encoded() {
+    return urlEncoded;
+  }
+
+  @Override
+  public int hashCode() {
+    return urlEncoded.hashCode();
+  }
+
+  @Override
+  public boolean equals(Object other) {
+    if (other instanceof IdString) {
+      return urlEncoded.equals(((IdString) other).urlEncoded);
+    } else if (other instanceof String) {
+      return urlEncoded.equals(other);
+    }
+    return false;
+  }
+
+  @Override
+  public String toString() {
+    return encoded();
+  }
+}

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

@@ -26,4 +26,9 @@ public class ResourceNotFoundException extends RestApiException {
   public ResourceNotFoundException(String id) {
     super(id);
   }
+
+  /** @param id portion of the resource URI that does not exist. */
+  public ResourceNotFoundException(IdString id) {
+    super(id.get());
+  }
 }

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

@@ -83,7 +83,7 @@ public interface RestCollection<P extends RestResource, R extends RestResource>
    * @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;
+  R parse(P parent, IdString id) throws ResourceNotFoundException, Exception;
 
   /**
    * Get the views that support this collection.