/*
 * 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(); }