Utilizar anotações nulas

NullPointerException é uma das causas mais comuns de falha dos programas Java. Nos casos mais simples, o compilador pode avisá-lo directamente quando visualiza código como este:

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

Com excepções de ramificação/colocação em ciclo e devolução bastante sofisticadas, a análise de fluxo torna-se necessária para descobrir se uma variável que está a ser referenciada foi atribuída a um valor nulo/não nulo em alguns ou em todos os caminhos através do programa.

Devido à complexidade inerente, a análise de fluxo é melhor executada em pequenas porções. A análise de um método de cada vez pode ser executada com uma boa ferramenta de desempenho - enquanto a análise de todo o sistema está fora do alcance de um compilador Java do Eclipse. A vantagem é: a análise é rápida e pode ser realizada de forma incremental, de modo a que o compilador o possa avisar directamente à medida que escreve. A desvantagem é: a análise não consegue "ver" quais os valores (nulos ou não nulos) que fluem entre os métodos (como parâmetros e valores de retorno).

Análise de nulos inter-procedimentos

É aqui que as anotações de nulos são importantes. Especificando um parâmetro de método como @NonNull pode dizer ao compilador que não quer um valor nulo nesta posição

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // verificação de nulos não necessária
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // é necessária verificação de nulos precedentes
    }

À luz de Design-by-Contract isto tem dois lados:

  1. É da responsabilidade do chamador nunca transmitir um valor nulo, que será assegurado, por exemplo, por uma verificação de nulos explícita.
  2. O implementador do método capitalizar desfruta da garantia de que o argumento in não será nulo e assim, anular a referência sem uma verificação de nulos aqui está bem.

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

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // a verificação de nulos em cima é necessária
        else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // não é necessária a verificação de nulos
    }
  1. Agora, o implementador tem de garantir que nunca é devolvido um valor nulo.
  2. Ao contrário, o chamador desfruta agora da garantia de que anular a referência do resultado do método sem a verificação está bem.

Anotações disponíveis

O compilador Java de Eclipse pode ser configurado para utilizar três tipos de anotação diferentes para a respectiva análise de nulos melhorada (que está desactivada por predefinição):

As anotações @NonNull e @Nullable são suportadas nessas localizações:

@NonNullByDefault é suportado para

Tenha em atenção, mesmo os nomes qualificados reais dessas anotações são configuráveis, mas, por predefinição, forem utilizados os fornecidos em cima (do pacote org.eclipse.jdt.annotation).

Configuração do caminho de construção

Um JAR com as anotações nulas predefinidas é comercializado com o Eclipse em eclipse/plugins/org.eclipse.jdt.annotation_*.jar. Este JAR tem de estar no caminho de construção no momento da compilação, mas não é necessário no tempo de execução (por isso não tem de ser enviado para os utilizadores do código compilado).

Existem duas correcções rápidas nas referências não solucionadas para @NonNull, @Nullable ou @NonNullByDefault que adicionam o JAR ao caminho de construção:

Interpretação de anotações nulas

Deveria ser claro agora que essas anotações nulas adicionam mais informação ao programa Java (que podem ser posteriormente utilizadas para facultar avisos melhores). Mas o que queremos exactamente que estas anotações digam? De um ponto de vista pragmático, existem pelo menos três níveis do que podemos pretender expressar com anotações nulas:

  1. Sugestões esporádicas para o leitor (humano e compilador)
  2. Desenho por contrato: especificação da API para alguns ou para todos os métodos
  3. Especificação completa utilizando um sistema de tipo expandido

Para (1) pode começar a utilizar anotações nulas no início e sem ler mais, mas não deverá esperar mais do que uma pequena sugestão de vez em quando. Os outros níveis merecem mais explicações.

Desenho por contrato: especificação da API

À primeira vista, utilizar anotações nulas para especificação da API à luz do Desenho por Contrato significa apenas que as assinaturas de todos os métodos da API devem ser completamente anotadas, ou seja, excepto para tipos primitivos como int, cada parâmetro e cada tipo de retorno de método deve ser marcado com @NonNull ou @Nullable. Uma vez que isso significaria inserir muitas anotações nulas, é bom saber que em código bem concebido (especialmente métodos da API), @NonNull é significativamente mais frequente do que @Nullable. Assim, o número de anotações pode ser reduzido declarando @NonNull como a predefinição, utilizando uma anotação @NonNullByDefault ao nível do pacote.

Tenha em atenção a diferença significativa entre @Nullable e omitir uma anotação nula: esta anotação indica explicitamente que nulo está bem e tem ser esperado. Por contraste, nenhuma anotação significa simplesmente que não conhecemos a intenção. Esta é a situação antiga onde por vezes ambos os lados (chamador e chamado) verificam de forma redundante se existem nulos, e por vezes ambos os lados assumem erradamente que o outro lado irá realizar a verificação. É daqui que origina NullPointerExceptions. Sem uma anotação, o compilador não irá fornecer conselhos específicos, mas com uma anotação @Nullable cada anulação de referência não verificada será sinalizada.

Com estes princípios básicos podemos correlacionar directamente todas as anotações de parâmetros com as pré-condições e interpretar as anotações de retorno como pós-condições do método.

Sub-inserção e substituição

Na programação orientada para os objectos, o conceito do Design por Contrato tem de abordar mais uma dimensão: sub-inserção e substituição (na sequência, o termo "substituição" será utilizado no sentido da anotação @Override em Java 6: métodos que substituem ou implementam outro método a partir de um super-tipo). Um cliente que invoca um método como este:

    @NonNull String checkedString(@Nullable String in)

deve ser permitido assumir que todas as implementações deste método cumprem o contrato. Por isso, quando a instrução do método é encontrada numa interface I1, temos de retirar a hipótese de que qualquer classe Cn que implemente I1 fornece uma implementação incompatível. Especificamente, é ilegal se qualquer Cn tentar substituir este método por uma implementação que declara o parâmetro como @NonNull. Se nós permitíssemos isso, um módulo de cliente programado relativamente a I1 poderia legalmente transmitir um valor nulo como o argumento, mas a implementação iria assumir um valor não nulo - seria permitido à anulação de referência não verificada dentro da implementação do método explodir no tempo de execução. Dessa forma, a especificação de um parâmetro @Nullable obriga todas as substituições a admitir um valor nulo como um valor esperado e legal.

Da forma inversa, uma especificação de retorno de @NonNull obriga todas as especificações a garantir que nunca será devolvido um valor nulo.

Por conseguinte, o compilador tem de verificar se nenhuma substituição adiciona uma anotação de parâmetro @NonNull (ou uma anotação de retorno @Nullable) que não exista no super-tipo.

Interessantemente, as redefinições inversas são legais: adicionar uma anotação de parâmetro @Nullable ou uma anotação de retorno @NonNull (poderá considerá-las melhorias do método, aceita mais valores e produz um valor de retorno mais específico).

Super-tipos de Legacy

As considerações anteriores adicionam uma dificuldade quando o código anotado é escrito como um subtipo de um tipo "legacy" (ou seja, não anotado) (que pode ser uma biblioteca de terceiros, ou seja, assim não pode ser alterado). Se ler a última secção atentamente, poderá ter reparado que não admitimos que um método "legacy" é substituído por um parâmetro @NonNull (uma vez que os clientes que utilizam o super-tipo não "vêem" a obrigação @NonNull).

Nesta situação será forçado a omitir as anotações nulas (existem planos para suportar adicionar as anotações a bibliotecas após o facto, mas ainda não pode ser feita nenhuma promessa, se e quando essa função estará disponível).

Cancelar uma predefinição de nullness

A situação será difícil, se um subtipo de um tipo "Legacy" residir num pacote para o qual foi especificado @NonNullByDefault. Agora, um tipo com um super-tipo não anotado teria de marcar todos os parâmetros nos métodos de substituição como @Nullable: mesmo omitindo anotações de parâmetros que não são permitidas porque seriam interpretadas como um parâmetro @NonNull, o que é proibido nessa posição. É por isso que o compilador Java do Eclipse suporta o cancelamento de uma predefinição de nullness: anotando um método ou tipo com @NonNullByDefault(false), uma predefinição aplicável será cancelada para este elemento, e os parâmetros não anotados serão novamente interpretados como não especificados. Agora, a sub-inserção é legal novamente sem adicionar anotações @Nullable não pretendidas:

class LegacyClass {
    String enhance (String in) { // os clientes não são forçados a transmitir valores não nulos.
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... método com predefinição @NonNull ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // seria válido se @NonNullByDefault fosse eficaz aqui
        return super.enhance(in);
    }
}

Vantagens do Design-by-Contract

Utilizando as anotações nulas no estilo de Design-by-Contract conforme especificado em cima, ajuda a melhorar a qualidade do código Java de diversas formas: na interface entre métodos é tornado explícito quais os parâmetros/retornos toleram um valor nulo e quais não. Isto capta decisões de desenho, que são altamente relevantes para os programadores, de uma forma que também é verificável pelo compilador.

Adicionalmente, com base na especificação desta interface, a análise do fluxo inter-procedimentos pode recolher informações disponíveis e fornecer erros/avisos muito mais precisos. Sem anotações, qualquer valor que flua para ou de um método tem um valor nullness desconhecido e, por conseguinte, permanece silencioso acerca da sua utilização. Com anotações nulas de nível da API, o valor nullness da maior parte dos valores é conhecida realmente, e significativamente menos NPE passarão despercebidas ao compilador. No entanto, deverá estar ciente de que continuam a existir algumas lacunas, onde os valores não especificados fluem para a análise, impedindo uma instrução completa, mesmo que as NPE possam ocorrer durante o tempo de execução.

Especificação completa utilizando um sistema de tipo expandido

O suporte para anotações nulas foi concebido de forma a ser compatível com uma extensão futura, para que o compilador possa garantir que um programa certificado nunca irá lançar uma NullPointerException no tempo de execução (com os contratempos típicos sobre partes não verificáveis como a reflexão). Embora ainda não se possa fazer nenhuma promessa relativamente a essa extensão futura, a ideia básica é uma interpretação diferente da que já temos.

Ao interpretar anotações nulas como parte de um sistema de tipos, duplicamos o número de tipos num determinado programa: para uma qualquer classe Cn, a própria classe já não é considerada como um tipo legal, mas apenas @NonNull Cn" e "@Nullable Cn" são tipos úteis. Por isso, idealmente, para cada valor num programa saberemos se pode ser nulo (e tem de ser seleccionado antes de anular a referência) ou não. Se excluirmos a terceira opção (tipos não anotados), então o compilador pode sinalizar de forma rigorosa cada utilização não segura.

A implementação actual tem duas grandes limitações relativamente a este objectivo:

A partir de hoje e apesar das limitações actuais, a visão de programas totalmente especificados e completamente verificados já tem algumas implicações que deram forma à análise actual e os erros/avisos relatados pelo compilador. Os detalhes serão apresentados explicando as regras que o compilador verifica e as mensagens que emite após a violação de uma regra.

Mensagens do compilador explicadas

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

Violação de especificação nula

Como violação de especificação, tratamos qualquer situação onde uma anotação nula afirma que é violada pela implementação real. A situação típica resulta da especificação de um valor (local, argumento, retorno de método) como @NonNull, enquanto a implementação fornece realmente um valor passível de ser nulo. Aqui, uma expressão é considerada como nullable se for estaticamente conhecida como avaliando para o valor nulo, ou se for declarada com uma anotação @Nullable.

Em segundo lugar, o grupo também contém as regras para a substituição de métodos, conforme discutido em cima. Aqui, um super método estabelece uma exigência (por exemplo, que null é um argumento legal) enquanto uma substituição tenta escapar a esta exigência (assumindo que null não é um argumento legal). Conforme mencionado, mesmo especializar um argumento a partir de não anotado para @NonNull é uma violação da especificação, porque introduz um contrato que deve associar o cliente (a não transmitir nulos), mas um cliente que está a utilizar o super tipo nem sequer irá ver este contrato, por isso, nem sabe o que se espera dele.

A lista completa de situações encaradas como violações de especificação é fornecida aqui. É importante compreender que os erros neste grupo nunca devem ser ignorados, porque, caso contrário, toda a análise de nulos seria executada com base em pressupostos falsos. Especificamente, sempre que o compilador vir um valor com uma anotação @NonNull, considera como certo que o valor nulo não irá ocorrer no tempo de execução. São as regras acerca das violações de especificações que garantem que este raciocínio é correcto. Por conseguinte, recomenda-se vivamente deixar este tipo de problema configurado como erros.

Conflito entre anotações nulas e inferência nula

Além disso, este grupo de regras observa a aderência a especificações nulas. No entanto, aqui lidamos com valores que não são declarados como @Nullable (nem o próprio valor nulo), mas os valores onde a análise de fluxo intra-procedimentos infere que o valor nulo pode ocorrer possivelmente em algum caminho de execução.

Esta situação surge do facto de para variáveis locais não anotadas o compilador irá inferir se o valor nulo é possível utilizando a respectiva análise de fluxo. Assumindo que esta análise é exacta, se encontrar um problema, esse problema tem a mesma gravidade que as violações directas de uma especificação de nulos. Por conseguinte, recomenda-se vivamente mais uma vez deixar estes problemas configurados como erros e a não ignorar estas mensagens.

Criar um grupo separado para estes problemas tem dois objectivos: documentar que um determinado problema foi posto com a ajuda da análise de fluxo, e: contabilizar o facto de que esta análise de fluxo poderia estar em falta (devido a um erro na implementação). Para o caso de uma implementação reconhecida, colocar o erro em situações excepcionais poderia não ter importância para suprimir uma mensagem de erro deste tipo.

Dada a natureza de qualquer análise estática, a análise de fluxo pode falhar ao ver que uma determinada combinação de caminhos e valores de execução não é possível. Como exemplo consideremos a correlação de variáveis:

   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]); // aviso aqui
        }
        if (sb1 != null) return sb1.append(sb2).toString();
        return "";
    }

O compilador irá registar um potencial indicador de nulos na invocação de sb2.append(..). O leitor humano consegue ver que não existe nenhum perigo real porque sb1 e sb2 correlacionam-se realmente de uma forma 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, dessa forma, também sb2 não é nulo. Sem entrar em detalhes sobre por que motivo essa análise de correlações está para além da capacidade do compilador Java do Eclipse, não se esqueça de que esta análise não tem o poder de um teorema completo e, por conseguinte, regista de forma pessimista alguns problemas que uma análise muito mais capaz poderia possivelmente identificar como alarmes falsos.

Se pretender beneficiar da análise de fluxo, aconselha-se a dar uma ajuda ao compilador para que possa "ver" as suas conclusões. Esta ajuda pode ser simples como dividir if (sb1 == null) em duas ifs separadas, uma para cada variável local, que é um pequeno preço a pagar pela vantagem de o compilador agora ver exactamente o que acontece e verificar o código em conformidade. Segue-se mais discussão sobre este tópico em baixo.

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

Este grupo de problemas baseia-se na seguinte analogia: num programa que utilize elementos genéricos de Java 5, quaisquer chamadas para bibliotecas pré-Java 5 podem expor tipos raw, ou seja, aplicações de um tipo genérico que falham ao especificar argumentos de tipo concreto. Para encaixar esses valores num programa utilizando elementos genéricos, o compilador pode adicionar uma conversão implícita assumindo que os argumentos de tipo foram especificados da forma esperada pelo cliente como parte do código. O compilador irá emitir um aviso sobre a utilização de uma conversão e continuar a verificação do tipo assumindo que a biblioteca "faz o correcto". Exactamente da mesma forma, um tipo de retorno não anotado de um método de biblioteca pode ser considerado como um tipo "raw" ou "legacy". Novamente uma conversão implícita pode assumir de forma optimista a especificação esperada. Novamente é emitido um aviso e a análise continua a assumir que a biblioteca "faz o correcto".

Teoricamente falando, também a necessidade dessas conversões implícitas indica uma violação de especificação. No entanto, neste caso pode ser código de terceiros que viola a especificação que o nosso código espera. Ou talvez (como nos convencemos) algum código de terceiros cumpre o contrato, mas apenas falha ao declará-lo (porque não utiliza anotações nulas). Nessas situações poderemos não conseguir corrigir exactamente o problema por motivos de organização.

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // conversão implícita
    foo.bar(); 

O fragmento de código em cima assume que Library.getFoo() devolve um Foo sem especificar uma anotação nula. Podemos integrar o valor de retorno para o nosso programa anotado por atribuição a uma variável local @NonNull, que activa um aviso relativamente a uma conversão não verificada. Ao adicionar o SuppressWarnings("null") correspondente a esta instrução reconhecemos o perigo inerente e aceitamos a responsabilidade de ter verificado que a biblioteca se comporta realmente como desejado.

Sugestões para tornar o código melhor analisável

Se a análise de fluxo não conseguir ver que um valor é de facto não nulo, a estratégia mais simples é sempre adicionar uma nova variável local de âmbito com @NonNull. Então, se está convencido de que o valor atribuído a este local nunca será nulo no tempo de execução pode utilizar métodos de ajuda como este:

    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, 
                    "valor não deve ser nulo porque a aplicação " +
                    "já está totalmente iniciada neste momento.");
            return theValue;
        }
        return new MyTypeImpl();
    }

Tenha em atenção que utilizar o método assertNonNull() em cima está a aceitar a responsabilidade de que esta afirmação será sempre mantida no tempo de execução. Se não for isto que pretende, as variáveis locais ajudarão ainda assim a restringir onde e por que motivo a análise vê um potencial para fluxo nulo para uma determinada localização.

Sugestões para adoptar anotações nulas

No momento da edição do JDT versão 3.8.0, recolher conselhos para adoptar anotações nulas é um trabalho ainda em curso. Por esse motivo, essas informações são actualmente mantidas no Eclipse wiki.