Por favor, lembre-se que esta tradução da especificação é resultado de um projeto da comunidade java.net( https://jdk5-api-pt-br.dev.java.net/). A versão oficial da especificação é a versão na língua inglesa que pode ser encontrada em http://java.sun.com/j2se/1.5.0/docs/api/. Em caso de divergências, a versão predominante da especificação é a original em inglês.

Please note that this translation of the specification is the result of a java.net community project ( https://jdk5-api-pt-br.dev.java.net/ ). The official version of the specification is the US English language version which can be found at http://java.sun.com/j2se/1.5.0/docs/api/. In case of disputes, the authoritative version of the specification is the original, English document.

java.util
Interface Map<K,V>

All Known Subinterfaces:

ConcurrentMap<K,V>, SortedMap<K,V>

All Known Implementing Classes:

AbstractMap, Attributes, AuthProvider, ConcurrentHashMap, EnumMap, HashMap, Hashtable, IdentityHashMap, LinkedHashMap, PrinterStateReasons, Properties, Provider, RenderingHints, TabularDataSupport, TreeMap, UIDefaults, WeakHashMap

public interface Map<K,V>

Um objeto que mapeia chaves e valores. Um map não pode conter chaves duplicadas; cada chave pode estar associada no máximo a um valor.

Esta interface substitui a classe Dictionary, que era na verdade uma classe abstrata ao invés de uma interface.

A interface Map fornece três visões de coleção, que permitem que o conteúdo do map seja visto como set de chaves, coleção de valores, ou set de pares chaves-valores mapeados. O ordenamento do map é definido pela ordem cujo iteratores de cada visão retornam seus elementos. Algumas implementações de map, como a classe TreeMap, estipulam garantias especifícas quanto ao seu ordenamento; outros, como a classe HashMap, não o fazem.

Nota: Deve-se tomar muito cuidado caso objetos mutáveis sejam usados como chave. O comportamento do map não é definido se o valor de um objeto for alterado de maneira que afete comparações com equals enquanto o objeto é uma chave no map. Um caso especial desta proibição é que não é permitido para um map conter ele próprio como uma chave. Apesar de ser permitido para um map conter ele próprio como um valor, cuidado extremo é necessário: os métodos equals e hashCode já não serão bem definidos em tal map.

Todas as classes de implementação de map de propósito geral devem fornecer dois consrutores "padrões": um construtor void (sem argumentos) que cria um map vazio, e um construtor com um único argumento do tipo Map, que cria um novo map com o mesmo mapeamento chave-valor de seu argumento. Na verdade, esse último construtor permite ao usuário copiar qualquer map, produzindo um map equivalente de uma classe desejada. Não existe maneiras de forçar essa recomendação (já que interfaces não possuem consrutores) mas todas as implementações de map de propósito geral no JDK serão compatíveis.

Os métodos "destrutivos" contidos nesta interface, ou seja, os métodos que modificam o map no qual eles operam, são especificados para lançar UnsupportedOperationException caso o map não suporte a operação. Se for o caso, esses métodos podem, mas não é requerido, lançar UnsupportedOperationException se a invocação não surtir efeitos no map. Por exemplo, invocando o método putAll(Map) em um map não modificável pode, mas não é requerido, lançar a exceção se o map cujo mapeamento estiver sendo "imposto" for vazio.

Algumas implementações de map possuem restrições quanto à chaves e valores que eles podem conter. Por exemplo, algumas implementações proíbem chaves e valores null, e algumas possuem restrições quanto ao tipo de suas chaves. Tentar inserir uma chave ou valor inválidos lança uma exceção não-checada, no caso NullPointerException ou ClassCastException. Tentar consultar a presença de uma chave ou valor inválidos pode lançar uma exceção, ou pode apenas retornar false; algumas implementações devem exibir o primeiro comportamento e outras o segundo. Mais geralmente, tentar uma operação em uma chave ou valor inválidos cujo resultado não seja a inserção de um elemento inválido no map pode lançar uma exceção ou pode suceder, fica a cargo da implementação. Exceções como essa são marcadas como "opcionais" na especificação para esta interface.

Esta interface é um membro do Java Collections Framework.

Vários métodos nas interfaces de Collections Framework são definidos em termos do método equals. Por exemplo, a especificação para o método contains(Object key) diz: "retorna true se, e apenas se este map contiver um mapeamento para chave k de forma que (key==null ? k==null : key.equals(k))." Essa especificação não deve implicar que invocando Map.containsKey com um argumento não nulo key faça com que key.equals(k) seja invocado para qualquer chave k. Implementações são livres para efetuar otimizações onde chamadas a equals são evitadas, por exemplo, para comparar o código hash de duas chaves. (A especificação de Object.hashCode() garante que dois objetos com códigos hash diferentes não podem ser iguais.) Mais geralmente, implementações das várias interfaces do Collections Framework são livres para se beneficiar do comportamento especificado para os métodos Object, onde o implementador julgar apropriado.

Since:

1.2

See Also:

HashMap, TreeMap, Hashtable, SortedMap, Collection, Set

Nested Class Summary

static interface

Map.Entry<K,V> Um map entry (par chave-valor).

Method Summary

void	clear() Remove todos os mapeamentos deste map (operação opcional).
boolean	containsKey(Object key) Retorna true se este map contiver um mapeamento para a chave especificada.
boolean	containsValue(Object value) Retorna true se este map mapeia uma ou mais chaves para o valor especificado.
Set<Map.Entry<K,V>>	entrySet() Retorna uma visão de set dos mapeamentos contidos neste map.
boolean	equals(Object o) Compara o objeto especificado com este map por igualdade.
V	get(Object key) Retorna o valor no qual este map mapeia a chave especificada.
int	hashCode() Retorna o valor de código hash para este map.
boolean	isEmpty() Retorna true se este map não contiver mapeamentos chave-valor.
Set<K>	keySet() Retorna uma visão de set das chaves contidas neste map.
V	put(K key, V value) Associa neste map o valor especificado com a chave especificada (operação opcional).
void	putAll(Map<? extends K,? extends V> t) Copia todo os mapeamentos do map especificado para este map (operação opcional).
V	remove(Object key) Remove o mapeamento no map para esta chave se houver (operação opcional).
int	size() Retorna o número de mapeamentos chave-valor neste map.
Collection<V>	values() Retorna uma visão de coleção dos valores contidos neste map.

Method Detail

size

int size()

Retorna o número de mapeamentos chave-valor neste map. Se o map contiver mais que Integer.MAX_VALUE elementos, retorna Integer.MAX_VALUE.

Returns:

número de mapeamentos chave-valor neste map.

isEmpty

boolean isEmpty()

Retorna true se este map não contiver mapeamentos chave-valor.

Returns:

true se este map não contiver mapeamentos chave-valor.

containsKey

boolean containsKey(Object key)

Retorna true se este map contiver um mapeamento para a chave especificada. Mais formalmene, retorna true se, e apenas se este map contiver um mapeamento para uma chave k de forma que (key==null ? k==null : key.equals(k)). (Obviamente deve existir no máximo um mapeamento como esse.)

Parameters:

key - chave cuja presença neste map deve ser testada.

Returns:

true se este map contiver um mapeamento para a chave especificada.

Throws:

ClassCastException - se a chave for de um tipo não apropriado para este map (opcional).

NullPointerException - se a chave for null e este map não permitir chaves null (opcional).

containsValue

boolean containsValue(Object value)

Retorna true se este map mapeia uma ou mais chaves para o valor especificado. Mais formalmente, retorna true se, e apenas se este map contiver no mínimo um mapeamento para o valor v de forma que (value==null ? v==null : value.equals(v)). Esta operação provavelmente deve requerer tempo linear no tamanho do map para maioria das implementações da interface Map.

Parameters:

value - valor cuja presença neste map deve ser testada.

Returns:

true se este map mapeia uma ou mais chaves para o valor especificado.

Throws:

ClassCastException - se o valor for de um tipo não apropriado para este map (opcional).

NullPointerException - se o valor for null e este map não permitir valores null (opcional).

get

V get(Object key)

Retorna o valor no qual este map mapeia a chave especificada. Retorna null se o map não contiver mapeamento para esta chave. Um valor de retorno null não indica necessariamente que o map não contém mapeamento para a chave; ainda é possível que o map tenha explicitamente mapeado a chave para null. A operação containsKey pode ser usada para distinguir entre esses dois casos.

Mais formalmente, se este map contiver o mapeamento de uma chave k para o valor v de forma que (key==null ? k==null : key.equals(k)), então este método retorna v; senão retorna null. (No máximo um mapeamento como este deve existir.)

Parameters:

key - chave cujo valor associado deve ser retornado.

Returns:

valor no qual o map mapeia a chave especificada, ou null se o map não contiver mapeamento para esta chave.

Throws:

ClassCastException - se a chave for de um tipo não apropriado para este map (opcional).

NullPointerException - se a chave for null e este map não permitir chaves null (opcional).

See Also:

containsKey(Object)

put

V put(K key,
      V value)

Associa neste map o valor especificado com a chave especificada (operação opcional). Se o map já contiver um mapeamento para esta chave, o antigo valor é substituído pelo valor especificado. (Um map m contém um mapeamento para a chave k se, e apenas se m.containsKey(k) retornar true.)

Parameters:

key - chave com a qual o valor especificado deve ser associado.

value - valor a ser associado à chave especificada.

Returns:

valor anterior associado à chave especificada, ou null se não existir mapeamento para a chave. Um retorno null pode também indicar que null estava associado com a chave especificada, caso a implementação suporte valores null.

Throws:

UnsupportedOperationException - se a operação put não for suportada por este map.

ClassCastException - se a classe da chave ou do valor especificado o previnem de serem armazenados neste map.

IllegalArgumentException - se algum aspecto da chave ou valor especificado o previnem de serem armazenados neste map.

NullPointerException - se este map não permitir chaves ou valores null, e a chave ou valor especificado for null.

remove

V remove(Object key)

Remove o mapeamento no map para esta chave se houver (operação opcional). Mais formalmente, se este map contiver um mapeamento da chave k para o valor v de forma que (key==null ? k==null : key.equals(k)), o mapeamento será removido. (O map pode conter no máximo um mapeamento como esse.)

Retorna o valor que o map associava à chave anteriormente, ou null se o map não contiver o mapeamento para esta chave. (Um retorno null pode também indicar que o map associava anteriormente null à chave especificada, no caso da implementação suportar valores null.) O map não deve conter um mapeamento para a chave especificada assim que o método retornar.

Parameters:

key - chave cujo mapeamento deverá ser removido do map.

Returns:

valor associado anteriormene à chave especificada, ou null se não existir mapeamento para a chave.

Throws:

ClassCastException - se a chave for de um tipo não apropriado para este map (opcional).

NullPointerException - se a chave for null e este map não permitir chaves null (opcional).

UnsupportedOperationException - se o método remove não for suportado por este map.

putAll

void putAll(Map<? extends K,? extends V> t)

Copia todo os mapeamentos do map especificado para este map (operação opcional). O efeito desta chamada é equivalente ao de put(k, v) uma vez para cada mapeamento da chave k ao valor v do map especificado. O comportamento desta operação é indefinido se o map especificado for modificado enquanto a operação estiver em progresso.

Parameters:

t - Mapeamentos a serem armazenados neste map.

Throws:

UnsupportedOperationException - se o método putAll não for suportado por este map.

ClassCastException - se a classe da chave ou do valor no map especificado o previne de ser armazenado neste map.

IllegalArgumentException - algum aspecto da chave ou do valor no map especificado o previne de ser armazenado neste map.

NullPointerException - se o map especificado for null, ou se este map não permite chaves ou valores null e o map especificado contiver chaves ou valores null.

clear

void clear()

Remove todos os mapeamentos deste map (operação opcional).

Throws:

UnsupportedOperationException - se este método não for suportado por este map.

keySet

Set<K> keySet()

Retorna uma visão de set das chaves contidas neste map. O set é suportado pelo map, portanto, alterações no map serão refletidas no set e vice-versa. Se o map for modificado enquanto uma iteração sobre o set estiver em progresso (exceto através da operação remove do próprio iterator), os resultados da iteração serão indefinidos. O set suporta remoção de elementos, no qual removerá o correspondente mapeamento do map, via operações Iterator.remove, Set.remove, removeAll, retainAll e clear. Não há suporte para operações add ou addAll.

Returns:

visão de set das chaves contidas neste map.

values

Collection<V> values()

Retorna uma visão de coleção dos valores contidos neste map. A coleção é suportada pelo map, portanto, alterações no map serão refletidas na coleção e vice-versa. Se o map for modificado enquanto uma iteração sobre a coleção estiver em progresso (exceto através da operação remove do próprio iterator), os resultados da iteração serão indefinidos. A coleção suporta remoção de elementos, no qual removerá o correspondente mapeamento do map, via operações Iterator.remove, Collection.remove, removeAll, retainAll e clear. Não há suporte para operações add ou addAll.

Returns:

visão de coleção dos valores contidos neste map.

entrySet

Set<Map.Entry<K,V>> entrySet()

Retorna uma visão de set dos mapeamentos contidos neste map. Cada elemento no set retornado é um Map.Entry. O set é suportado pelo map, portanto, alterações no map serão refletidas no set e vice-versa. Se o map for modificado enquanto uma iteração sobre o set estiver em progresso (exceto através da operação remove do próprio iterator ou através da operação setValue no map entry retornado pelo iterator), os resultados da iteração serão indefinidos. O set suporta remoção de elementos, no qual removerá o correspondente mapeamento do map, via operações Iterator.remove, Set.remove, removeAll, retainAll e clear. Não há suporte para operações add ou addAll.

Returns:

visão de set dos mapeamentos contidos neste map.

equals

boolean equals(Object o)

Compara o objeto especificado com este map por igualdade. Retorna true se o dado objeto for também um map e os dois maps representarem os mesmos mapeamentos. Mais formalmente, dois maps t1 e t2 representam os mesmos mapeamentos se t1.entrySet().equals(t2.entrySet()). Isto assegura que o método equals funcione apropriadamente entre diferentes implementações da interface Map.

Overrides:

equals in class Object

Parameters:

o - objeto a ser comparado por igualdade com este map.

Returns:

true se o objeto especificado for igual a este map.

See Also:

Object.hashCode(), Hashtable

hashCode

int hashCode()

Retorna o valor de código hash para este map. O código hash de um map é defino como a soma dos códigos hash de cada entrada na visão entrySet do map. Isto assegura que t1.equals(t2) implica que t1.hashCode()==t2.hashCode() para quaisquer dois maps t1 e t2, como requerido pelo contrato geral de Object.hashCode.

Overrides:

hashCode in class Object

Returns:

valor de código hash para este map.

See Also:

Map.Entry.hashCode(), Object.hashCode(), Object.equals(Object), equals(Object)