Usando Anotações Nulas

NullPointerException é uma das causas mais comuns de falha de programas Java. Nos casos mais simples, o compilador pode avisar diretamente quando aparece um código semelhante a este:

    Object o = null;
    String s = o.toString();

Com exceções de ramificação, loop e lançadas, uma análise de fluxo bem sofisticada torna-se necessária para descobrir se a variável que está sendo desreferenciada recebeu um valor nulo/não nulo em algum caminho ou em todos os caminhos no programa.

Devido à complexidade inerente, a análise de fluxo é melhor executada em chunks pequenos. A análise de um método por vez pode ser executada com um bom desempenho da ferramenta, porém a análise de todo o sistema está fora do escopo do compilador Java Eclipse. A vantagem é: a análise é rápida e pode ser executada de forma incremental de modo que o compilador pode avisá-lo diretamente à medida que você digita. O ponto fraco: a análise não consegue "ver" quais valores (nulos ou não nulos) estão fluindo entre os métodos (como valores de parâmetro e de retorno).

Análise nula interprocessual

É aqui que as anotações nulas entram em cena. Ao especificar um parâmetro de método como @NonNull, é possível informar o compilador que você não deseja um valor nulo nessa posição.

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // no null check required
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // preceding null check is required
    }

No contexto de Padrão por Contrato isso tem dois lados:

  1. É responsabilidade do responsável pela chamada nunca passar um valor nulo, o que deve ser assegurado, por exemplo, por uma verificação explícita de nulo.
  2. Assim, o implementador do método capitalize tem a garantia de que o argumento in não deve ser nulo e a desreferência pode ser realizada sem uma verificação de nulo.

Para os valores de retorno do método, a situação é simétrica:

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // the above null check is required
        else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // no null check required
    }
  1. Agora, o implementador deve assegurar-se de que nulo nunca é retornado.
  2. Por outro lado, o responsável pela chamada tem agora a garantia de que a desreferência do resultado do método pode ser feita sem verificação.

Anotações disponíveis

O compilador Java Eclipse pode ser configurado para usar três tipos distintos de anotação para a análise de nulo aprimorada (desativada por padrão):

As anotações @NonNull e @Nullable são suportadas nestes locais:

@NonNullByDefault é suportado para

Observe que, mesmo os nomes qualificados reais dessas anotações são configuráveis, mas, por padrão, são usados os indicados acima (a partir do pacote org.eclipse.jdt.annotation).

Configuração do caminho de construção

Um JAR com as anotações nulas padrão é enviado com Eclipse em eclipse/plugins/org.eclipse.jdt.annotation_*.jar. Este JAR precisa estar no caminho de construção no tempo de compilação, mas não é necessário no tempo de execução (portanto, não é necessário enviar isto aos usuários do seu código compilado).

Há duas correções rápidas em referências não resolvidas a @NonNull, @Nullable ou @NonNullByDefault que incluem o JAR no caminho de construção:

Interpretação de anotações de nulo

Agora deve estar claro que as anotações de nulo incluem mais informações no programa Java (que poderão ser usadas pelo compilador para fornecer avisos melhores). Mas o que, exatamente, queremos que essas anotações informem? De um ponto de vista pragmático, há pelo menos três níveis do que podemos expressar com as anotações de nulo:

  1. Sugestões esporádicas ao leitor (humano e compilador)
  2. Padrão por Contrato: Especificação de API para alguns ou todos os métodos
  3. Especificação completa usando um sistema de tipos estendido

Para (1) você pode iniciar o uso das anotações de nulo imediatamente e sem continuar a leitura, mas você não deve esperar mais do que uma pequena sugestão de vez em quando. Os outros níveis requerem mais explicações.

Padrão por Contrato: especificação de API

A primeira vista, o uso de anotações de nulo para especificação de API no contexto de Padrão por Contrato apenas significa que as assinaturas de todos os métodos de API devem ser completamente anotadas, por exemplo, exceto para os tipos primitivos como int, cada tipo de parâmetro e de retorno do método deve ser marcado como @NonNull ou @Nullable. Como isso significaria inserir inúmeras anotações de nulo, é bom saber que em códigos bem projetados (principalmente métodos de API), @NonNull é significativamente mais frequente do que @Nullable. Portanto, o número de anotações pode ser reduzido ao declarar @NonNull como o padrão, usando uma anotação @NonNullByDefault no nível do pacote.

Observe a diferença significativa entre @Nullable e a omissão de uma anotação de nulo: Essa anotação indica explicitamente que nulo é correto e deve ser esperado. Por outro lado, a ausência de anotação significa simplesmente que não sabemos qual é a intenção. Essa é a antiga situação em que, às vezes, ambos os lados (responsável pela chamada e destinatário da chamada) fazem a verificação de nulo em redundância e, algumas vezes, ambos os lados assumem incorretamente que o outro lado fará a verificação. Essa é a situação a partir da qual NullPointerExceptions se origina. Sem as anotações, o compilador não fornecerá avisos específicos, mas com uma anotação @Nullable, cada desreferência não verificada será sinalizada.

Com essas considerações básicas, é possível mapear diretamente todas as anotações de parâmetro para pré-condições e interpretar as anotações de retorno como pós-condições do método.

Subtipo e substituição

Na programação orientada a objetos, o conceito de Padrão por Contrato precisa abordar uma dimensão a mais: subtipo e substituição (na sequência, o termo "substituir" será usado no sentido da anotação @Override no Java 6: métodos que substituem ou implementam outro método a partir de um supertipo). Um cliente que chama um método como o seguinte:

    @NonNull String checkedString(@Nullable String in)

deve ter permissão para assumir que todas as implementações desse método preenchem o contrato. Portanto, quando a declaração do método for localizada em uma interface I1, deverá ser descartado que qualquer classe Cn que implemente I1 fornecerá uma implementação incompatível. Especificamente, será considerado ilegal se qualquer Cn tentar substituir esse método por uma implementação que declare o parâmetro como @NonNull. Se isso fosse permitido, um módulo de cliente programado com relação a I1 poderia, legalmente, passar nulo como o argumento, mas a implementação assumiria um valor não nulo. Uma desreferência não verificada dentro da implementação do método seria permitida, mas não funcionaria no tempo de execução. Portanto, uma especificação de parâmetro @Nullable obriga todas as substituições a admitirem nulo como um valor legal e esperado.

Por outro lado, uma especificação de retorno @NonNull obriga todas as substituições a assegurarem que nulo nunca será retornado.

Portanto, o compilador precisa verificar se nenhuma substituição inclui uma anotação de parâmetro @NonNull (ou uma anotação de retorno @Nullable) que não existia no supertipo).

Curiosamente, as redefinições reversas são legais: a inclusão de uma anotação de parâmetro @Nullable ou de uma anotação de retorno @NonNull (você pode considerar isso como "melhorias" do método, pois ele aceita mais valores e produz um valor de retorno mais específico).

Supertipos legados

As considerações anteriores possuem um problema quando o código anotado é escrito como um subtipo de um tipo "legado" (por exemplo, não anotado) (que pode ser de uma biblioteca de terceiros, portanto, que não pode ser alterada). Se você tiver lido a última seção com bastante cuidado, talvez tenha observado que não é possível admitir que um método "legado" seja substituído por um método com um parâmetro @NonNull (pois os clientes que usam o supertipo não "veem" a obrigação de @NonNull).

Nessa situação, você será forçado a omitir as anotações de nulo (existem planos para suportar a inclusão de anotações para bibliotecas após a execução, mas ainda não é possível prometer se e quando esse recurso ficará disponível).

Cancelando um padrão de nulidade

A situação ficará delicada se um subtipo de um tipo "legado" residir em um pacote para o qual o @NonNullByDefault tenha sido especificado. Agora, um tipo com um supertipo não anotado precisaria marcar todos os parâmetros nos métodos de substituição como @Nullable: até mesmo a omissão de anotações de parâmetro não é permitida porque ela seria interpretada como um parâmetro @NonNull, que é proibido nessa posição. É por isso que o compilador Java Eclipse suporta o cancelamento de um padrão de nulidade: ao anotar um método ou tipo com @NonNullByDefault(false), um padrão aplicável será cancelado para esse elemento e os parâmetros não anotados serão novamente interpretados como não especificados. Agora, o subtipo é novamente legal sem a inclusão de anotações @Nullable não desejadas:

class LegacyClass {
    String enhance (String in) { // clients are not forced to pass nonnull.
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... methods with @NonNull default ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // would not be valid if @NonNullByDefault were effective here
        return super.enhance(in);
    }
}

Benefícios do Padrão por Contrato

O uso de anotações de nulo no estilo de Padrão por Contrato, conforme descrito acima, ajuda a melhorar a qualidade do código Java de várias maneiras: Na interface entre os métodos fica explícito quais parâmetros/retornos toleram um valor nulo e quais não toleram. Isso captura as decisões de design, que são altamente relevantes para os desenvolvedores, de uma maneira também verificável pelo compilador.

Além disso, com base nessa especificação de interface, a análise de fluxo intra-procedural pode selecionar as informações disponíveis e fornecer erros/avisos muito mais precisos. Sem as anotações, qualquer valor que flui para dentro e para fora de um método possui nulidade desconhecida e, portanto, a análise de nulo continua em silencio quanto ao seu uso. Com as anotações de nulo no nível da API, a nulidade da maioria dos valores é, de fato, conhecida e significativamente menos NPEs passam despercebidos pelo compilador. No entanto, você deve estar ciente de que ainda há algumas brechas, nas quais valores não especificados fluem para a análise, impedindo uma declaração completa sobre se NPEs poderão ocorrer no tempo de execução.

Especificação completa usando um sistema de tipos estendido

O suporte para as anotações de nulo foi projetado para que seja compatível com uma extensão futura, em que o compilador será capaz de garantir que um programa certificado nunca lançará um NullPointerException no tempo de execução (com as advertências típicas quanto a partes não verificadas como reflexo). Embora nenhuma promessa possa ser feita ainda com relação a essa extensão futura, a ideia básica é apenas uma interpretação diferente daquela que já existe.

Ao interpretar as anotações de nulo como parte do sistema de tipos, o número de tipos em um determinado programa é dobrado: para qualquer classe determinada Cn, a classe em si não é mais considerada um tipo legal, mas apenas "@NonNull Cn" e "@Nullable Cn" são tipos úteis. Portanto, em condições ideais, saberemos se cada valor em um programa poderá ser nulo ou não (e isso deverá ser verificado antes de desreferenciar). Se excluirmos a terceira opção (tipos não anotados), o compilador poderá sinalizar rigorosamente cada uso não seguro.

A implementação atual possui duas grandes limitações relacionadas ao seu objetivo:

A partir de agora e independentemente das limitações atuais, a visão de programas totalmente especificados e completamente verificados já possui algumas implicações que formam a análise atual e os erros/avisos relatados pelo compilador. Os detalhes serão apresentados nas explicações sobre as regras que o compilador verifica e as mensagens que ele emite quando há uma violação de regra.

Mensagens do compilador explicadas

Na página de preferências correspondente, as regras individuais verificadas pelo compilador estão sob os seguintes cabeçalhos:

Violação de especificação de nulo

Qualquer situação em que uma anotação de nulo fizer uma afirmação de que foi violada pela implementação real será tratada como uma violação de especificação. A situação típica resulta da especificação de um valor (local, argumento, retorno do método) como @NonNull, em que, na verdade, a implementação fornece um valor nulo. Aqui, uma expressão será considerada como anulável se for conhecida estaticamente por ser avaliada para o valor nulo ou se for declarada com uma anotação @Nullable.

Em segundo lugar, esse grupo também contém as regras para os métodos de substituição, conforme discutido acima. Aqui, um super método estabelece uma afirmação (por exemplo, que nulo é um argumento legal) enquanto uma substituição tenta esquivar-se dessa afirmação (ao assumir que nulo não é um argumento legal). Conforme mencionado, mesmo a especialização de um argumento de não anotado para @NonNull é uma violação de especificação, porque apresenta um contrato que deve estar ligado ao cliente (para não passar nulo), mas um cliente que usar o supertipo não verá esse contrato, portanto, ele não saberá o que se espera dele.

A lista completa de situações consideradas violações de especificação é fornecida aqui. É importante entender que os erros nesse grupo nunca devem ser ignorados, porque se forem, a análise de nulo inteira será executada com base em suposições falsas. Especificamente, sempre que o compilador encontrar um valor com uma anotação @NonNull, ele assumirá que não ocorrerá nulo no tempo de execução. São as regras sobre violações de especificação que asseguram que esse raciocínio esteja correto. Portanto, é altamente recomendado deixar esse tipo de problema configurado como erros.

Conflito entre anotações de nulo e inferência de nulo

Além disso, esse grupo de regras zela pela adesão às especificações de nulo. No entanto, aqui estamos lidando com valores que não são declarados como @Nullable (nem o próprio valor nulo), mas com valores em que a análise de fluxo intra-procedural infere que nulo provavelmente poderá ocorrer em algum caminho de execução.

Essa situação suscita do fato de que para variáveis locais não anotadas, o compilador inferirá se nulo é possível usando sua análise de fluxo. Supondo que essa análise seja precisa, se um problema for encontrado, ele terá a mesma severidade que as violações diretas de uma especificação de nulo. Portanto, novamente é altamente recomendado deixar esses problemas configurados como erros e não ignorar essas mensagens.

A criação de um grupo separado para esses problemas possui dois propósitos: documentar que um determinado problema foi encontrado com a ajuda da análise de fluxo e para considerar o fato de que essa análise de fluxo pode estar com falha (devido a um erro na implementação). No caso de um erro de implementação reconhecido, em situações excepcionais, talvez seja possível suprimir uma mensagem de erro desse tipo.

Dada a natureza de qualquer análise estática, a análise de fluxo poderá não perceber que uma determinada combinação de caminhos e valores de execução não é possível. Como exemplo, considere a correlação de variável:

   String flatten(String[] inputs1, String[] inputs2) { 
        StringBuffer sb1 = null, sb2 = null;
        int len = Math.min(inputs1.length, inputs2.length);
        for (int i=0; i<len; i++) {
            if (sb1 == null) {
                sb1 = new StringBuffer();
                sb2 = new StringBuffer();
            }
            sb1.append(inputs1[i]);
            sb2.append(inputs2[i]); // warning here
        }
        if (sb1 != null) return sb1.append(sb2).toString();
        return "";
    }

O compilador relatará um acesso de ponteiro nulo potencial na chamada de sb2.append(..). O leitor humano poderá verificar se não há um perigo real porque sb1 e sb2, na verdade, se correlacionam de uma maneira em que ambas as variáveis são nulas ou ambas são não nulas. Na linha em questão, sabemos que sb1 não é nulo, portanto, sb2 também não é nulo. Sem entrar em detalhes sobre porque essa análise de correlação está além da capacidade do compilador Java Eclipse, tenha em mente que essa análise não tem o poder de uma prova completa de teorema e, portanto, relata de forma negativa alguns problemas que uma análise mais capaz poderia provavelmente identificar como alarmes falsos.

Se você desejar se beneficiar da análise de fluxo, é aconselhado dar uma pequena ajuda ao compilador para que ele possa "ver" suas conclusões. Essa ajuda pode ser muito simples, como dividir if (sb1 == null) em dois arquivos separados, um para cada variável local, que é um pequeno preço a pagar para ganhar a vantagem de que o compilador poderá saber exatamente o que ocorre e verificar o código da maneira apopriada. Mais discussão sobre esse tópico será apresentada abaixo.

Conversão não verificada do tipo não anotado para o tipo @NonNull

Esse grupo de problemas é baseado na seguinte analogia: em um problema que usa genéricos do Java 5, as chamadas para bibliotecas pré-Java 5 podem expor tipos brutos, ou seja, os aplicativos de um tipo genérico que falham ao especificar argumentos de tipo concretos. Para ajustar esses valores em um programa que usa genéricos, o compilador pode incluir uma conversão implícita assumindo que os argumentos de tipos tenham sido especificados da maneira esperada pelo cliente parte do código. O compilador emitirá um aviso sobre o uso dessa conversão e continuará sua verificação de tipo assumindo que a biblioteca "faz a coisa certa". Exatamente da mesma maneira, um tipo de retorno não anotado de um método de biblioteca pode ser considerado um tipo "bruto" ou "legado". Novamente, uma conversão implícita pode assumir de forma otimista a especificação esperada. Novamente um aviso será emitido e a análise continuará a assumir que a biblioteca "faz a coisa certa".

Teoricamente, a necessidade dessas conversões implícitas também indica uma violação de especificação. No entanto, nesse caso, pode ser um código de terceiros que viola a especificação que o nosso código espera. Ou, talvez (conforme nos convencemos) algum código de terceiro que cumpre o contrato, mas falha ao declarar isso (porque ele não usa anotações de nulo). Nessas situações, talvez não seja possível corrigir exatamente o problema por motivos organizacionais.

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // implicit conversion
    foo.bar(); 

O fragmento de código acima assume que Library.getFoo() retorna um Foo sem especificar uma anotação de nulo. É possível integrar o valor de retorno em nosso programa anotado por designação a uma variável local @NonNull que aciona um aviso relacionado a uma conversão não verificada. Ao incluir um SuppressWarnings("null") correspondente nessa declaração, reconhecemos o perigo inerente e aceitamos a responsabilidade de ter verificado que a biblioteca realmente se comporta conforme desejado.

Dicas para tornar o código melhor para analisar

Se a análise de fluxo não puder verificar se um valor é realmente nulo, a estratégia mais simples é sempre incluir uma nova variável local com escopo definido anotada com @NonNull. Em seguida, se você estiver convencido de que o valor designado a esse local nunca será nulo no tempo de execução, será possível usar um método auxiliar como o seguinte:

    static @NonNull <T> T assertNonNull(@Nullable T value, @Nullable String msg) {
        if (value == null) throw new AssertionError(msg);
        return value;
    }
    @NonNull MyType foo() {
        if (isInitialized()) {
            MyType couldBeNull = getObjectOrNull();
            @NonNull MyType theValue = assertNonNull(couldBeNull, 
                    "value should not be null because application " +
                    "is fully initialized at this point.");
            return theValue;
        }
        return new MyTypeImpl();
    }

Observe que usando o método assertNonNull() acima, você está aceitando a responsabilidade de que essa asserção sempre será retida no tempo de execução. Se não for isso o que você deseja, as variáveis locais anotadas ainda ajudarão a limitar onde e porque a análise reconhece um nulo potencial fluindo para um determinado local.

Dicas para adotar anotações de nulo

No momento da liberação do JDT versão 3.8.0, a coleta de aviso para a adoção de anotações de nulo ainda é um trabalho em andamento. Por esse motivo, essas informações ainda são mantidas na Wiki do Eclipse.