É melhor retornar um ImmutableMap ou um Mapa?

Digamos que estou escrevendo um método que deve retornar um Mapa . Por exemplo:

public Map<String, Integer> foo() {
  return new HashMap<String, Integer>();
}

Depois de pensar um pouco, decidi que não há razão para modificar este mapa depois de criado. Portanto, gostaria de retornar um ImmutableMap .

public Map<String, Integer> foo() {
  return ImmutableMap.of();
}

Devo deixar o tipo de retorno como um Mapa genérico ou devo especificar que estou retornando um ImmutableMap?

De um lado, é exatamente para isso que as interfaces foram criadas; para ocultar os detalhes de implementação.
Por outro lado, se eu deixar assim, outros desenvolvedores podem perder o fato de que esse objeto é imutável. Portanto, não alcançarei o objetivo principal de objetos imutáveis; para tornar o código mais claro, minimizando o número de objetos que podem ser alterados. Pior ainda, depois de um tempo, alguém pode tentar alterar este objeto, e isso resultará em um erro de execução (o compilador não avisará sobre isso).

• Se você está escrevendo uma API voltada para o público e essa imutabilidade é um aspecto importante do seu design, eu definitivamente tornaria isso explícito fazendo com que o nome do método denote claramente que o mapa retornado será imutável ou retornando o tipo concreto de o mapa. Mencioná-lo no javadoc não é suficiente em minha opinião.

  Visto que você aparentemente está usando a implementação Guava, olhei para o documento e é uma classe abstrata, portanto, oferece um pouco de flexibilidade no tipo real e concreto.

• Se você está escrevendo uma ferramenta / biblioteca interna, torna-se muito mais aceitável apenas retornar um plano Map. As pessoas saberão sobre os detalhes internos do código para o qual estão ligando ou pelo menos terão fácil acesso a ele.

Minha conclusão seria que explícito é bom, não deixe as coisas ao acaso.

Você deve ter ImmutableMapcomo seu tipo de retorno. Mapcontém métodos que não são suportados pela implementação de ImmutableMap(por exemplo put) e são marcados @deprecatedcom ImmutableMap.

O uso de métodos obsoletos resultará em um aviso do compilador e a maioria dos IDEs avisará quando as pessoas tentarem usar os métodos obsoletos.

Este aviso avançado é preferível a ter exceções de tempo de execução como sua primeira dica de que algo está errado.

Por outro lado, se eu deixar assim, outros desenvolvedores podem perder o fato de que esse objeto é imutável.

Você deve mencionar isso nos javadocs. Os desenvolvedores os leem, você sabe.

Portanto, não alcançarei o objetivo principal de objetos imutáveis; para tornar o código mais claro, minimizando o número de objetos que podem ser alterados. Pior ainda, depois de um tempo, alguém pode tentar alterar este objeto, e isso resultará em um erro de execução (o compilador não avisará sobre isso).

Nenhum desenvolvedor publica seu código não testado. E quando ele o testa, ele recebe uma Exceção onde ele não apenas vê o motivo, mas também o arquivo e a linha onde ele tentou gravar em um mapa imutável.

Observe, porém, que apenas o Mappróprio será imutável, não os objetos que ele contém.

se eu deixar assim, outros desenvolvedores podem perder o fato de que este objeto é imutável

Isso é verdade, mas outros desenvolvedores devem testar seu código e garantir que ele seja coberto.

No entanto, você tem mais 2 opções para resolver isso:

• Use Javadoc

  @return a immutable map

• Escolha um nome descritivo para o método

  public Map<String, Integer> getImmutableMap()
  public Map<String, Integer> getUnmodifiableEntries()

  Para um caso de uso concreto, você pode até nomear melhor os métodos. Por exemplo

  public Map<String, Integer> getUnmodifiableCountByWords()

O que mais você pode fazer?!

Você pode devolver um

• cópia de

  private Map<String, Integer> myMap;
  
  public Map<String, Integer> foo() {
    return new HashMap<String, Integer>(myMap);
  }

  Essa abordagem deve ser usada se você espera que muitos clientes modifiquem o mapa e desde que o mapa contenha apenas algumas entradas.

• CopyOnWriteMap

  As coleções de cópia na gravação geralmente são usadas quando você precisa lidar com a
  simultaneidade. Mas o conceito também o ajudará em sua situação, já que um CopyOnWriteMap cria uma cópia da estrutura de dados interna em uma operação mutativa (por exemplo, adicionar, remover).

  Nesse caso, você precisa de um wrapper fino em torno de seu mapa que delega todas as invocações de método para o mapa subjacente, exceto as operações mutativas. Se uma operação mutativa for chamada, ela criará uma cópia do mapa subjacente e todas as outras chamadas serão delegadas a essa cópia.

  Essa abordagem deve ser usada se você espera que alguns clientes modifiquem o mapa.

  Infelizmente, o java não tem tal CopyOnWriteMap. Mas você pode encontrar um terceiro ou implementá-lo sozinho.

Por fim, você deve ter em mente que os elementos em seu mapa ainda podem ser mutáveis.

Definitivamente, retorne um ImmutableMap, com a justificativa:

• A assinatura do método (incluindo o tipo de retorno) deve ser autodocumentada. Comentários são como atendimento ao cliente: se seus clientes precisam confiar neles, seu produto principal está com defeito.
• Se algo é uma interface ou uma classe, só é relevante ao estender ou implementar. Dada uma instância (objeto), 99% das vezes o código do cliente não saberá ou se importará se algo é uma interface ou uma classe. Presumi a princípio que ImmutableMap era uma interface. Só depois de clicar no link é que percebi que é uma aula.

Depende da própria classe. O Guava ImmutableMapnão pretende ser uma visão imutável em uma classe mutável. Se sua classe for imutável e tiver alguma estrutura que seja basicamente um ImmutableMap, faça o tipo de retorno ImmutableMap. No entanto, se sua classe for mutável, não faça isso. Se você tem este:

public ImmutableMap<String, Integer> foo() {
    return ImmutableMap.copyOf(internalMap);
}

O Guava irá copiar o mapa todas as vezes. Isso é lento. Mas se internalMapjá era um ImmutableMap, então está tudo bem.

Se você não restringir sua classe para retornar ImmutableMap, então você pode retornar desta Collections.unmodifiableMapforma:

public Map<String, Integer> foo() {
    return Collections.unmodifiableMap(internalMap);
}

Observe que esta é uma visão imutável no mapa. Se internalMapmudar, uma cópia em cache de Collections.unmodifiableMap(internalMap). Eu ainda prefiro para getters, no entanto.

Isso não está respondendo à pergunta exata, mas ainda vale a pena considerar se um mapa deve ser devolvido. Se o mapa for imutável, o método principal a ser fornecido será baseado em get (key):

public Integer fooOf(String key) {
    return map.get(key);
}

Isso torna a API muito mais rígida. Se um mapa for realmente necessário, isso pode ser deixado para o cliente da API, fornecendo um fluxo de entradas:

public Stream<Map.Entry<String, Integer>> foos() {
    map.entrySet().stream()
}

Em seguida, o cliente pode fazer seu próprio mapa imutável ou mutável conforme necessário ou adicionar as entradas a seu próprio mapa. Se o cliente precisa saber se o valor existe, opcional pode ser retornado em seu lugar:

public Optional<Integer> fooOf(String key) {
    return Optional.ofNullable(map.get(key));
}

Mapa imutável é um tipo de mapa. Portanto, não há problema em deixar o tipo de retorno de Mapa.

Para garantir que os usuários não modifiquem o objeto retornado, a documentação do método pode descrever as características do objeto retornado.

Isso é indiscutivelmente uma questão de opinião, mas a melhor ideia aqui é usar uma interface para a classe de mapa. Esta interface não precisa dizer explicitamente que é imutável, mas a mensagem será a mesma se você não expor nenhum dos métodos setter da classe pai na interface.

Dê uma olhada no seguinte artigo:

Andy Gibson