Package org.apache.solr.common.util

# Class NamedList<T>

java.lang.Object
org.apache.solr.common.util.NamedList<T>

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Iterable<Map.Entry<String,T>>`, `MapSerializable`, `MapWriter`, `NavigableObject`, `org.noggit.JSONWriter.Writable`

Direct Known Subclasses:
  `CloudSolrClient.RouteResponse`, `SimpleOrderedMap`

public class NamedList<T> extends Object implements Cloneable, Serializable, Iterable<Map.Entry<String,T>>, MapWriter
A simple container class for modeling an ordered list of name/value pairs.

Unlike Maps:

- Names may be repeated
- Order of elements is maintained
- Elements may be accessed by numeric index
- Names and Values can both be null

A NamedList provides fast access by element number, but not by name.

When a NamedList is serialized, order is considered more important than access by key, so ResponseWriters that output to a format such as JSON will normally choose a data structure that allows order to be easily preserved in various clients (i.e. not a straight map). If access by key is more important for serialization, see `SimpleOrderedMap`, or simply use a regular `Map`

See Also:
  - Serialized Form

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static final class`
`NamedList.NamedListEntry<T>`
Deprecated.

## Nested classes/interfaces inherited from interface org.apache.solr.common.MapWriter

`MapWriter.EntryWriter`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final List<Object>`
`nvPairs`

### Fields inherited from interface org.apache.solr.common.MapWriter

`EMPTY`

## Constructor Summary

Constructors
Constructor
Description
`NamedList()`
Creates an empty instance
`NamedList(int sz)`
`NamedList(Map.Entry<String,? extends T>[] nameValuePairs)`
Creates a NamedList instance containing the "name,value" pairs contained in the Entry[].
`NamedList(Map<String,? extends T> nameValueMap)`
Creates a NamedList instance containing the "name,value" pairs contained in the Map.

## Method Summary

Modifier and Type
Method
Description
`void`
`add(String name, T val)`
Adds a name/value pair to the end of the list.
`boolean`
`addAll(Map<String,T> args)`
Iterates over the Map and sequentially adds its key/value pairs
`boolean`
`addAll(NamedList<? extends T> nl)`
Appends the elements of the given NamedList to this one.
`Map`
`asMap(int maxDepth)`
`Map<String,T>`
`asShallowMap()`
Deprecated.
Use `SimpleOrderedMap` instead.
`Map<String,T>`
`asShallowMap(boolean allowDps)`
Deprecated.
use `SimpleOrderedMap` instead of NamedList when a Map is required.
`void`
`clear()`
`NamedList<T>`
`clone()`
Makes a shallow copy of the named list.
`boolean`
`equals(Object obj)`
`void`
`forEach(BiConsumer<? super String,? super T> action)`
`T`
`get(String name)`
Gets the value for the first instance of the specified name found.
`T`
`get(String name, int start)`
Deprecated.
Use `indexOf(String, int)` then `getVal(int)`.
`List<T>`
`getAll(String name)`
Gets the values for the specified name
`Boolean`
`getBooleanArg(String name)`
Used for getting a boolean argument from a NamedList object.
`NamedList<T>`
`getImmutableCopy()`
`String`
`getName(int idx)`
The name of the pair at the specified List index
`T`
`getOrDefault(String name, T def)`
Like `get(String)` but returns a default value if it would be null.
`T`
`getVal(int idx)`
The value of the pair at the specified List index
`int`
`hashCode()`
`int`
`indexOf(String name)`
Scans the names of the list sequentially beginning at index 0 and returns the index of the first pair with the specified name.
`int`
`indexOf(String name, int start)`
Scans the list sequentially beginning at the specified index and returns the index of the first pair with the specified name.
`Iterator<Map.Entry<String,T>>`
`iterator()`
Support the Iterable interface
`T`
`remove(int idx)`
Removes the name/value pair at the specified index.
`T`
`remove(String name)`
NOTE: this runs in linear time (it scans starting at the beginning of the list until it finds the first pair with the specified name).
`List<T>`
`removeAll(String name)`
Removes and returns all values for the specified name.
`Boolean`
`removeBooleanArg(String name)`
Used for getting a boolean argument from a NamedList object.
`Collection<String>`
`removeConfigArgs(String name)`
Used for getting one or many arguments from NamedList objects that hold configuration parameters.
`void`
`setName(int idx, String name)`
Modifies the name of the pair at the specified index.
`T`
`setVal(int idx, T val)`
Modifies the value of the pair at the specified index.
`int`
`size()`
The total number of name/value pairs
`SolrParams`
`toSolrParams()`
Create SolrParams from NamedList.
`String`
`toString()`
`void`
`writeMap(MapWriter.EntryWriter ew)`
Writes this object's entries out to `ew`.

### Methods inherited from class java.lang.Object

`finalize, getClass, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

### Methods inherited from interface org.apache.solr.common.MapWriter

`jsonStr, toMap, write`

### Methods inherited from interface org.apache.solr.common.NavigableObject

`_forEachEntry, _forEachEntry, _forEachEntry, _get, _get, _getStr, _getStr, _size`

## Field Details

### nvPairs

protected final List<Object> nvPairs

## Constructor Details

### NamedList

public NamedList()
Creates an empty instance

### NamedList

public NamedList(int sz)

### NamedList

public NamedList(Map.Entry<String,? extends T>[] nameValuePairs)
Creates a NamedList instance containing the "name,value" pairs contained in the Entry[].

Modifying the contents of the Entry[] after calling this constructor may change the NamedList (in future versions of Solr), but this is not guaranteed and should not be relied upon. To modify the NamedList, refer to `add(String, Object)` or `remove(String)`.

Parameters:
  `nameValuePairs` - the name value pairs

### NamedList

public NamedList(Map<String,? extends T> nameValueMap)
Creates a NamedList instance containing the "name,value" pairs contained in the Map.

Modifying the contents of the Map after calling this constructor may change the NamedList (in future versions of Solr), but this is not guaranteed and should not be relied upon. To modify the NamedList, refer to `add(String, Object)` or `remove(String)`.

Parameters:
  `nameValueMap` - the name value pairs

## Method Details

### writeMap

public void writeMap(MapWriter.EntryWriter ew) throws IOException
Description copied from interface: `MapWriter`
Writes this object's entries out to `ew`.

Specified by:
  `writeMap` in interface `MapWriter`
Throws:
  `IOException`

### size

public int size()
The total number of name/value pairs

### getName

public String getName(int idx)
The name of the pair at the specified List index

Returns:
  null if no name exists

### getVal

public T getVal(int idx)
The value of the pair at the specified List index

Returns:
  may be null

### add

public void add(String name, T val)
Adds a name/value pair to the end of the list.

### setName

public void setName(int idx, String name)
Modifies the name of the pair at the specified index.

### setVal

public T setVal(int idx, T val)
Modifies the value of the pair at the specified index.

Returns:
  the value that used to be at index

### remove

public T remove(int idx)
Removes the name/value pair at the specified index.

Returns:
  the value at the index removed

### indexOf

public int indexOf(String name, int start)
Scans the list sequentially beginning at the specified index and returns the index of the first pair with the specified name.

Parameters:
  `name` - name to look for, may be null
  `start` - index to begin searching from
Returns:
  The index of the first matching pair, -1 if no match

### indexOf

public int indexOf(String name)
Scans the names of the list sequentially beginning at index 0 and returns the index of the first pair with the specified name.

See Also:
  - `indexOf(String, int)`

### get

public T get(String name)
Gets the value for the first instance of the specified name found.

NOTE: this runs in linear time (it scans starting at the beginning of the list until it finds the first pair with the specified name).

Returns:
  null if not found or if the value stored was null.
See Also:
  - `indexOf(java.lang.String, int)`
  - `get(String,int)`

### getOrDefault

public T getOrDefault(String name, T def)
Like `get(String)` but returns a default value if it would be null.

### get

@Deprecated public T get(String name, int start)
Deprecated.
Use `indexOf(String, int)` then `getVal(int)`.
Gets the value for the first instance of the specified name found starting at the specified index.

NOTE: this runs in linear time (it scans starting at the specified position until it finds the first pair with the specified name).

Returns:
  null if not found or if the value stored was null.
See Also:
  - `indexOf(java.lang.String, int)`

### getAll

public List<T> getAll(String name)
Gets the values for the specified name

Parameters:
  `name` - Name
Returns:
  List of values

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### getImmutableCopy

public NamedList<T> getImmutableCopy()

### asShallowMap

@Deprecated public Map<String,T> asShallowMap()
Deprecated.
Use `SimpleOrderedMap` instead.

### asShallowMap

@Deprecated public Map<String,T> asShallowMap(boolean allowDps)
Deprecated.
use `SimpleOrderedMap` instead of NamedList when a Map is required.

### asMap

public Map asMap(int maxDepth)

### toSolrParams

public SolrParams toSolrParams()
Create SolrParams from NamedList. Values must be `String[]` or `List` (with toString()-appropriate entries), or otherwise have a toString()-appropriate value. Nulls are retained as such in arrays/lists but otherwise will NPE.

### addAll

public boolean addAll(Map<String,T> args)
Iterates over the Map and sequentially adds its key/value pairs

### addAll

public boolean addAll(NamedList<? extends T> nl)
Appends the elements of the given NamedList to this one.

### clone

public NamedList<T> clone()
Makes a shallow copy of the named list.

Overrides:
  `clone` in class `Object`

### iterator

public Iterator<Map.Entry<String,T>> iterator()
Support the Iterable interface

Specified by:
  `iterator` in interface `Iterable<T>`

### remove

public T remove(String name)
NOTE: this runs in linear time (it scans starting at the beginning of the list until it finds the first pair with the specified name).

### removeAll

public List<T> removeAll(String name)
Removes and returns all values for the specified name. Returns null if no matches found. This method will return all matching objects, regardless of data type. If you are parsing Solr config options, the `removeConfigArgs(String)` or `removeBooleanArg(String)` methods will probably work better.

Parameters:
  `name` - Name
Returns:
  List of values

### removeBooleanArg

public Boolean removeBooleanArg(String name)
Used for getting a boolean argument from a NamedList object. If the name is not present, returns null. If there is more than one value with that name, or if the value found is not a Boolean or a String, throws an exception. If there is only one value present, and it is a Boolean or a String, the value is removed and returned as a Boolean. If an exception is thrown, the NamedList is not modified. See `removeAll(String)` and `removeConfigArgs(String)` for additional ways of gathering configuration information from a NamedList.

Parameters:
  `name` - The key to look up in the NamedList.
Returns:
  The boolean value found.
Throws:
  `SolrException` - If multiple values are found for the name or the value found is not a Boolean or a String.

### getBooleanArg

public Boolean getBooleanArg(String name)
Used for getting a boolean argument from a NamedList object. If the name is not present, returns null. If there is more than one value with that name, or if the value found is not a Boolean or a String, throws an exception. If there is only one value present, and it is a Boolean or a String, the value is returned as a Boolean. The NamedList is not modified. See `remove(String)`, `removeAll(String)` and `removeConfigArgs(String)` for additional ways of gathering configuration information from a NamedList.

Parameters:
  `name` - The key to look up in the NamedList.
Returns:
  The boolean value found.
Throws:
  `SolrException` - If multiple values are found for the name or the value found is not a Boolean or a String.

### removeConfigArgs

public Collection<String> removeConfigArgs(String name) throws SolrException
Used for getting one or many arguments from NamedList objects that hold configuration parameters. Finds all entries in the NamedList that match the given name. If they are all strings or arrays of strings, remove them from the NamedList and return the individual elements as a `Collection`. Parameter order will be preserved if the returned collection is handled as an `ArrayList`. Throws SolrException if any of the values associated with the name are not strings or arrays of strings. If exception is thrown, the NamedList is not modified. Returns an empty collection if no matches found. If you need to remove and retrieve all matching items from the NamedList regardless of data type, use `removeAll(String)` instead. The `removeBooleanArg(String)` method can be used for retrieving a boolean argument.

Parameters:
  `name` - The key to look up in the NamedList.
Returns:
  A collection of the values found.
Throws:
  `SolrException` - If values are found for the input key that are not strings or arrays of strings.

### clear

public void clear()

### hashCode

public int hashCode()

Overrides:
  `hashCode` in class `Object`

### equals

public boolean equals(Object obj)

Overrides:
  `equals` in class `Object`

### forEach

public void forEach(BiConsumer<? super String,? super T> action)