ratpack.util.MultiValueMap Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of ratpack-exec Show documentation
The Ratpack Execution Model
There is a newer version: 2.0.0-rc-1
/*
 * 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.util;

import com.google.common.collect.ListMultimap;
import ratpack.api.Nullable;
import ratpack.util.internal.ImmutableDelegatingMultiValueMap;

import java.util.List;
import java.util.Map;

/**
 * A map that may contain multiple values for a given key, but typically only one value.
 * 
 * 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.
 * 

 * All implementations of this type are immutable. Mutating operations throw {@link UnsupportedOperationException}.
 * 

 * Where there is multiple values for a given key, retrieving a single value will return the first value,
 * where the first value is intrinsic to the service in which the map is being used.
 *
 * @param  The type of key objects
 * @param  The type of value objects
 */
public interface MultiValueMap extends Map {

  static  MultiValueMap empty() {
    return ImmutableDelegatingMultiValueMap.empty();
  }

  /**
   * All of the values for the given key. An empty list if there are no values for the key.
   * 

   * 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 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).
   * 
   * 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> 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
   */
  @Nullable
  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 m);

  /**
   * Throws {@link UnsupportedOperationException}.
   *
   * {@inheritDoc}
   */
  void clear();

  ListMultimap asMultimap();

}