Add Tests to Ratpack Framework Support

java/ql/test/stubs/ratpack-1.9.x/ratpack/func/MultiValueMap.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2013 the original author or authors.
+ *
+ * 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 ratpack.func;
+
+import com.google.common.collect.ListMultimap;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A map that may contain multiple values for a given key, but typically only one value.
+ * <p>
+ * Unlike other multi map types, this type is optimized for the case where there is only one value for a key.
+ * The map acts just like a normal {@link Map}, but has extra methods for getting all values for a key.
+ * <p>
+ * <b>All implementations of this type are immutable.</b> Mutating operations throw {@link UnsupportedOperationException}.
+ * <p>
+ * Where there is multiple values for a given key, retrieving a single value will return the <i>first</i> value,
+ * where the first value is intrinsic to the service in which the map is being used.
+ *
+ * @param <K> The type of key objects
+ * @param <V> The type of value objects
+ */
+public interface MultiValueMap<K, V> extends Map<K, V> {
+
+  static <K, V> MultiValueMap<K, V> empty() {
+    return null;
+  }
+
+  /**
+   * All of the values for the given key. An empty list if there are no values for the key.
+   * <p>
+   * The returned list is immutable.
+   *
+   * @param key The key to return all values of
+   * @return all of the values for the given key, or an empty list if there are no values for the key.
+   */
+  List<V> getAll(K key);
+
+  /**
+   * Returns a new view of the map where each map value is a list of all the values for the given key (i.e. a traditional multi map).
+   * <p>
+   * The returned map is immutable.
+   * @return A new view of the map where each map value is a list of all the values for the given key
+   */
+  Map<K, List<V>> getAll();
+
+  /**
+   * Get the first value for the key, or {@code null} if there are no values for the key.
+   *
+   * @param key The key to obtain the first value for
+   * @return The first value for the given key, or {@code null} if there are no values for the given key
+   */
+  V get(Object key);
+
+  /**
+   * Throws {@link UnsupportedOperationException}.
+   *
+   * {@inheritDoc}
+   */
+  V put(K key, V value);
+
+  /**
+   * Throws {@link UnsupportedOperationException}.
+   *
+   * {@inheritDoc}
+   */
+  V remove(Object key);
+
+  /**
+   * Throws {@link UnsupportedOperationException}.
+   *
+   * {@inheritDoc}
+   */
+  @SuppressWarnings("NullableProblems")
+  void putAll(Map<? extends K, ? extends V> m);
+
+  /**
+   * Throws {@link UnsupportedOperationException}.
+   *
+   * {@inheritDoc}
+   */
+  void clear();
+
+  ListMultimap<K, V> asMultimap();
+
+}