/*
 * Copyright (c) 2011-2017 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.http.CaseInsensitiveHeaders;

import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.function.Predicate;

This class represents a MultiMap of String keys to a List of String values.

It's useful in Vert.x to represent things in Vert.x like HTTP headers and HTTP parameters which allow
multiple values for keys.
Author:
Norman Maurer, Tim Fox/**
 * This class represents a MultiMap of String keys to a List of String values.
 * <p>
 * It's useful in Vert.x to represent things in Vert.x like HTTP headers and HTTP parameters which allow
 * multiple values for keys.
 *
 * @author <a href="mailto:nmaurer@redhat.com">Norman Maurer</a>
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
@VertxGen
public interface MultiMap extends Iterable<Map.Entry<String, String>> {

  
Create a multi-map implementation with case insensitive keys, for instance it can be used to hold some HTTP headers.
Returns:
the multi-map/**
   * Create a multi-map implementation with case insensitive keys, for instance it can be used to hold some HTTP headers.
   *
   * @return the multi-map
   */
  static MultiMap caseInsensitiveMultiMap() {
    return new CaseInsensitiveHeaders();
  }

  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  String get(CharSequence name);

  
Returns the value of with the specified name.  If there are
more than one values for the specified name, the first value is returned.
Params:
name – The name of the header to search
Returns:
The first header value or null if there is no such entry/**
   * Returns the value of with the specified name.  If there are
   * more than one values for the specified name, the first value is returned.
   *
   * @param name The name of the header to search
   * @return The first header value or {@code null} if there is no such entry
   */
  @Nullable String get(String name);

  
Returns the values with the specified name
Params:
name – The name to search
Returns:
A immutable List of values which will be empty if no values are found/**
   * Returns the values with the specified name
   *
   * @param name The name to search
   * @return A immutable {@link java.util.List} of values which will be empty if no values
   *         are found
   */
  List<String> getAll(String name);

  
Like getAll(String) but accepting a CharSequence as a parameter /**
   * Like {@link #getAll(String)} but accepting a {@code CharSequence} as a parameter
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  List<String> getAll(CharSequence name);

  
Returns all entries in the multi-map.
Returns:
A immutable List of the name-value entries, which will be empty if no pairs are found/**
   * Returns all entries in the multi-map.
   *
   * @return A immutable {@link java.util.List} of the name-value entries, which will be
   *         empty if no pairs are found
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  List<Map.Entry<String, String>> entries();

  
Checks to see if there is a value with the specified name
Params:
name – The name to search for
Returns:
true if at least one entry is found/**
   * Checks to see if there is a value with the specified name
   *
   * @param name The name to search for
   * @return true if at least one entry is found
   */
  boolean contains(String name);

  
Like contains(String) but accepting a CharSequence as a parameter /**
   * Like {@link #contains(String)} but accepting a {@code CharSequence} as a parameter
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  boolean contains(CharSequence name);

  
Check if there is a header with the specified name and value. If caseInsensitive is true, value is compared in a case-insensitive way. 
Params:
name – the name to search for
value – the value to search for
Returns:
true if at least one entry is found/**
   * Check if there is a header with the specified {@code name} and {@code value}.
   *
   * If {@code caseInsensitive} is {@code true}, {@code value} is compared in a case-insensitive way.
   *
   * @param name the name to search for
   * @param value the value to search for
   * @return {@code true} if at least one entry is found
   */
  default boolean contains(String name, String value, boolean caseInsensitive) {
    return getAll(name).stream()
      .anyMatch(val -> caseInsensitive ? val.equalsIgnoreCase(value) : val.equals(value));
  }

  
Like contains(String, String, boolean) but accepting CharSequence parameters. /**
   * Like {@link #contains(String, String, boolean)} but accepting {@code CharSequence} parameters.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  default boolean contains(CharSequence name, CharSequence value, boolean caseInsensitive) {
    Predicate<String> predicate;
    if (caseInsensitive) {
      String valueAsString = value.toString();
      predicate = val -> val.equalsIgnoreCase(valueAsString);
    } else {
      predicate = val -> val.contentEquals(value);
    }
    return getAll(name).stream().anyMatch(predicate);
  }

  
Return true if empty
/**
   * Return true if empty
   */
  boolean isEmpty();

  
Gets a immutable Set of all names 
Returns:
A Set of all names/**
   * Gets a immutable {@link java.util.Set} of all names
   *
   * @return A {@link java.util.Set} of all names
   */
  Set<String> names();

  
Adds a new value with the specified name and value.
Params:
name – The name
value – The value being added
Returns:
a reference to this, so the API can be used fluently/**
   * Adds a new value with the specified name and value.
   *
   * @param name The name
   * @param value The value being added
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  MultiMap add(String name, String value);

  
Like add(String, String) but accepting CharSequence as parameters /**
   * Like {@link #add(String, String)} but accepting {@code CharSequence} as parameters
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap add(CharSequence name, CharSequence value);

  
Adds a new values under the specified name
Params:
name – The name being set
values – The values
Returns:
a reference to this, so the API can be used fluently/**
   * Adds a new values under the specified name
   *
   * @param name The name being set
   * @param values The values
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap add(String name, Iterable<String> values);

  
Like add(String, Iterable<String>) but accepting CharSequence as parameters /**
   * Like {@link #add(String, Iterable)} but accepting {@code CharSequence} as parameters
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap add(CharSequence name, Iterable<CharSequence> values);

  
Adds all the entries from another MultiMap to this one
Returns:
a reference to this, so the API can be used fluently/**
   * Adds all the entries from another MultiMap to this one
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  MultiMap addAll(MultiMap map);

  
Adds all the entries from a Map to this
Returns:
a reference to this, so the API can be used fluently/**
   * Adds all the entries from a Map to this
   *
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap addAll(Map<String, String> headers);

  
Sets a value under the specified name.

If there is an existing header with the same name, it is removed.
Params:
name – The name
value – The value
Returns:
a reference to this, so the API can be used fluently/**
   * Sets a value under the specified name.
   * <p>
   * If there is an existing header with the same name, it is removed.
   *
   * @param name The name
   * @param value The value
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  MultiMap set(String name, String value);

  
Like set(String, String) but accepting CharSequence as parameters /**
   * Like {@link #set(String, String)} but accepting {@code CharSequence} as parameters
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap set(CharSequence name, CharSequence value);

  
Sets values for the specified name.
Params:
name – The name of the headers being set
values – The values of the headers being set
Returns:
a reference to this, so the API can be used fluently/**
   * Sets values for the specified name.
   *
   * @param name The name of the headers being set
   * @param values The values of the headers being set
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap set(String name, Iterable<String> values);

  
Like set(String, Iterable<String>) but accepting CharSequence as parameters /**
   * Like {@link #set(String, Iterable)} but accepting {@code CharSequence} as parameters
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap set(CharSequence name, Iterable<CharSequence> values);

  
Cleans this instance.
Returns:
a reference to this, so the API can be used fluently/**
   * Cleans this instance.
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  MultiMap setAll(MultiMap map);

  
Cleans and set all values of the given instance
Returns:
a reference to this, so the API can be used fluently/**
   * Cleans and set all values of the given instance
   *
   * @return a reference to this, so the API can be used fluently
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap setAll(Map<String, String> headers);

 
Removes the value with the given name
Params:
name – The name  of the value to remove
Returns:
a reference to this, so the API can be used fluently/**
  * Removes the value with the given name
  *
  * @param name The name  of the value to remove
  * @return a reference to this, so the API can be used fluently
  */
  @Fluent
  MultiMap remove(String name);

  
Like remove(String) but accepting CharSequence as parameters /**
   * Like {@link #remove(String)} but accepting {@code CharSequence} as parameters
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  MultiMap remove(CharSequence name);

  
Removes all
Returns:
a reference to this, so the API can be used fluently/**
   * Removes all
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  MultiMap clear();

  
Return the number of keys.
/**
   * Return the number of keys.
   */
  int size();

}