Utilización de las anotaciones de nulos

NullPointerException es una de las causas más habituales de error de los programas Java. En los casos más sencillos, el compilador puede advertirle directamente cuando ve código como el siguiente:

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

Con la bifurcación/reproducción en bucle y la generación de excepciones, se impone la necesidad de un análisis de flujo bastante sofisticado para poder dilucidar si una variable cuya referencia se va a eliminar se ha asignado a un valor nulo o no en alguna o en todas las vías de acceso del programa.

Debido a su complejidad inherente, el análisis de flujo se realiza mejor en pequeños fragmentos. El análisis de los métodos uno a uno se puede realizar con un buen rendimiento de herramienta, mientras que el compilador Java de Eclipse no abarca el análisis de todo el sistema. La ventaja es que el análisis es más rápido y se puede realizar de forma incremental, de manera que el compilador pueda avisarle directamente mientras escribe. El inconveniente es que el análisis no puede "ver" los valores (nulos o no nulos) que fluyen entre los métodos (como parámetros y valores de retorno).

Análisis de nulos entre procedimientos

Aquí es donde entran en juego las anotaciones de nulos. Especificando un parámetro de método como @NonNull puede indicar al compilador que no desea un valor nulo en esta posición.

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // comprobación de nulos no necesaria
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // la comprobación de nulos anterior es necesaria
    }

Según el estilo Diseño por contrato, esto tiene dos caras:

  1. El llamante es el responsable de no pasar nunca un valor nulo, lo cual se debe garantizar, por ejemplo, mediante una comprobación de nulos explícita.
  2. El implementador del método capitalize cuenta con la garantía de que el argumento in no será nulo y, por lo tanto, la eliminación de referencia sin una comprobación de nulos es adecuada en este caso.

En el caso de los valores de retorno, la situación es simétrica:

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // la comprobación de nulos anterior es necesaria
        else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // no es necesaria ninguna comprobación de nulos
    }
  1. Ahora el implementador debe asegurarse de que no se devuelve nunca un nulo.
  2. Por el contrario, el llamante ahora cuenta con la garantía de que la eliminación de la referencia del resultado del método sin comprobación es adecuada.

Anotaciones disponibles

El compilador Java de Eclipse puede configurarse para utiliza tres tipos de anotaciones distintas para su análisis mejorado de nulos (que está inhabilitado de manera predeterminada):

Se da soporte a las anotaciones @NonNull y @Nullable en estas ubicaciones:

Se da soporte a @NonNullByDefault para:

Tenga en cuenta que los nombres calificados reales de estas anotaciones se pueden configurar , aunque de manera predeterminada se utilizan los que se indican anteriormente (del paquete org.eclipse.jdt.annotation).

Configuración de la vía de acceso de construcción

Un JAR con las anotaciones nulas predeterminadas se envía con Eclipse en eclipse/plugins/org.eclipse.jdt.annotation_*.jar. Este JAR debe estar en la vía de acceso de construcción en tiempo de compilación pero no es necesario en tiempo de ejecución (por lo que no tiene que enviarle esto a los usuarios del código compilado).

Hay dos arreglos rápidos en referencias no resueltas a @NonNull, @Nullableo @NonNullByDefault que añaden el JAR a la vía de acceso de construcción:

Interpretación de las anotaciones de nulos

Ahora debe quedar claro que las anotaciones de nulos añaden más información al programa Java (que el compilador puede utilizar, a continuación, para ofrecer mejores avisos). No obstante, ¿qué deseamos que indiquen exactamente esas anotaciones? Desde un punto de vista pragmático existen, por lo menos, tres niveles que puede que deseemos expresar con las anotaciones de nulos:

  1. Consejos esporádicos para el lector (persona o compilador)
  2. Diseño por contrato: especificación de API para algunos métodos o para todos
  3. Especificación completa con un sistema de tipo ampliado

En el caso (1), es posible que desee empezar utilizando anotaciones de nulos directamente y sin más lecturas, pero no debería esperar más que un pequeño consejo de vez en cuando. Los demás niveles merecen una explicación más detallada.

Diseño por contrato: especificación de API

A primera vista, el uso de anotaciones de nulos para especificaciones de API según el estilo Diseño por contrato sólo significa que las firmas de todos los métodos de API deben estar totalmente anotadas, es decir, salvo en el caso de los tipos primitivos como int, cada parámetro y cada tipo de retorno de método debe marcarse como @NonNull o @Nullable. Puesto que esto implicaría insertar muchas anotaciones de nulos, conviene saber que en el código bien diseñado (especialmente métodos de API), @NonNull es considerablemente más frecuente que @Nullable. Por lo tanto, el número de anotaciones se puede reducir declarando @NonNull como valor predeterminado, mediante una anotación @NonNullByDefault en el nivel de paquete.

Tenga en cuenta la diferencia significativa que existe entre @Nullable y omitir una anotación de nulos: esta anotación indica explícitamente que un nulo es adecuado y debe esperarse. En cambio, ninguna anotación significa que no sabemos cuál es la intención. Se trata del viejo problema en el que en ocasiones los dos extremos (llamante y llamado) comprobaban de forma redundante la existencia de nulos y en ocasiones los dos extremos presuponían que el otro extremo realizaría la comprobación. Aquí está el origen de las NullPointerExceptions. Sin una anotación, el compilador no ofrecerá el consejo específico, pero con una anotación @Nullable se marcará cada eliminación de referencia sin comprobar.

Con estos conceptos básicos podemos correlacionar directamente todas las anotaciones de parámetro con condiciones previas e interpretar las anotaciones de retorno como condiciones posteriores del método.

Creación de subtipos y alteración temporal

En la programación orientada a objetos, el concepto de Diseño por contrato tiene que abordar una dimensión adicional: la creación de subtipos y la alteración temporal (en adelante el término "alteración temporal" se utilizará en el sentido de la anotación @Override de Java 6: métodos que alteran temporalmente o implementan otro método de un supertipo). Un cliente que invoca un método con el siguiente:

    @NonNull String checkedString(@Nullable String in)

Debe poder presuponer que todas las implementaciones de este método cumplen el contrato. Cuando la declaración de método, pues, se encuentra en una interfaz I1, debemos descartar que ninguna clase Cn que implemente I1 proporcione una implementación incompatible. De forma específica, no está permitido que una Cn intente alterar temporalmente este método con una implementación que declare el parámetro como @NonNull. Si lo permitiéramos, un módulo de cliente programado con I1 podría pasar un nulo de forma lícita como argumento, pero la implementación presupondría un valor no nulo: se permitiría una eliminación de referencia no comprobada dentro de la implementación de método, pero ésta estallaría en tiempo de ejecución. Por lo tanto, una especificación de parámetro @Nullable obliga a que todas las alteraciones temporales admitan nulos como valores esperados permitidos.

Por el contrario, una especificación de retorno @NonNull obliga a que todas las alteraciones temporales garanticen que no se devolverá jamás un nulo.

Por lo tanto, el compilador tiene que comprobar que ninguna alteración temporal añada una anotación de parámetro @NonNull (o una anotación de retorno @Nullable) que no existiera en el supertipo.

Lo interesante es que las redefiniciones inversas están permitidas: añadir una anotación de parámetro @Nullable o una anotación de retorno @NonNull (puede considerarlas como "mejoras" del método: acepta más valores y generar un valor de retorno más específico).

Supertipos heredados

Las consideraciones anteriores añaden una dificultad cuando el código anotado se escribe como subtipo de un tipo "heredado" (es decir, no anotado) que puede ser de una biblioteca de otro proveedor y, por lo tanto, no se puede cambiar. Si ha leído el apartado anterior con atención, es posible que haya observado que no podemos admitir que un método "heredado" sea alterado temporalmente por un método con un parámetro @NonNull (porque los clientes que utilizan el supertipo no "ven" la obligación de @NonNull).

En esta situación, se verá en la obligación de omitir las anotaciones de nulos (se prevé dar soporte a la adición de anotaciones a bibliotecas a posteriori, aunque no se promete nada aún, cuando dicha característica esté disponible y en el caso que lo esté).

Cancelación de un valor predeterminado de ausencia de nulos

La cosa se complicará si un subtipo de un tipo "heredado" reside en un paquete para el que se ha especificado @NonNullByDefault. Ahora un tipo con un supertipo no anotado tendría que marcar todos los parámetros de los métodos de alteración temporal como @Nullable: incluso la omisión de anotaciones de parámetro no está permitida porque ello se interpretaría como un parámetro @NonNull, que está prohibido en esta posición. Por ello el compilador Java de Eclipse da soporte a la cancelación de un valor predeterminado de ausencia de nulos: anotando un método o un tipo con @NonNullByDefault(false), se cancelará un valor predeterminado aplicable para este elemento y los parámetros no anotados se vuelven a interpretar como no especificados. Ahora la creación de subtipos vuelve a estar permitida sin añadir anotaciones @Nullable no deseadas:

class LegacyClass {
    String enhance (String in) { // los clientes no se ven forzados a pasar valores no nulos.
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... métodos con el valor predeterminado @NonNull ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // no serían válidos si @NonNullByDefault fuera efectivo aquí
        return super.enhance(in);
    }
}

Ventajas de Diseño por contrato

El uso de anotaciones de nulos según el estilo Diseño por contrato, tal como se señalaba anteriormente, ayuda a mejorar la calidad del código Java de varias maneras: en la interfaz entre los métodos se explicitan los parámetros o valores de retorno que toleran un valor nulo y los que no. Se evidencian las decisiones de diseño, que son extremadamente importantes para los desarrolladores, de manera que el compilador también lo pueda comprobar.

Además, según la especificación de interfaz, el análisis de flujo dentro del procedimiento puede recoger la información disponible y ofrecer errores o avisos mucho más precisos. Sin las anotaciones, ningún valor que fluya hasta o desde un método tiene una ausencia de nulos desconocida y, por lo tanto, el análisis de nulos no se pronuncia sobre su uso. Con las anotaciones de nulos de nivel de API, la ausencia de nulos de la mayoría de valores se reconoce realmente y el compilador no detectará un número considerablemente menor de NPE. Sin embargo, debe tener presente que siguen existiendo algunas lagunas, a raíz de las cuales valores no especificados fluyen hacia el análisis e impiden una sentencia completa por la que se puedan producir NPE en tiempo de ejecución.

Especificación completa mediante un sistema de tipos ampliado

El soporte para anotaciones de nulos se ha diseñado de manera que es compatible con una ampliación futura, por la que el compilador podrá garantizar que un programa certificado no generará una NullPointerException en tiempo de ejecución (con las advertencias habituales sobre las partes no comprobables como el reflejo). Aunque no se puede prometer nada aún en cuanto a dicha futura ampliación, la idea básica es otra interpretación de lo que ya hemos explicado.

Al interpretar las anotaciones de nulos como parte del sistema de tipos, duplicamos el número de tipos de un programa concreto: para cualquier clase Cn determinada, la propia clase ya no se considera un tipo legal y sólo "@NonNull Cn" y "@Nullable Cn" son tipos útiles. Por lo tanto, lo ideal es que sepamos si cada valor de un programa puede ser nulo (y si se deben comprobar antes de la eliminación de la referencia). Si excluimos la tercera opción (tipos no anotados), el compilador puede marcar de forma estricta todos los usos no seguros.

La implementación actual tiene dos limitaciones principales por lo que se refiere a este objetivo:

Actualmente y a pesar de las limitaciones actuales, la visión de programas totalmente especificados y comprobados por completo ya tiene algunas implicaciones que han modelado el análisis actual y los errores y avisos notificados por el compilador. Los detalles se presentarán explicando las reglas que el compilador comprueba y los mensajes que emite tras la infracción de una regla.

Explicación de los mensajes del compilador

En la página de preferencias correspondiente, se enumeran las reglas individuales que comprueba el compilador bajo las cabeceras siguientes:

Violación de la especificación de nulos

Se maneja como violación de especificación cualquier situación en la que una anotación de nulos alega que la implementación real la ha violado. La situación habitual se produce cuando se especifica un valor (local, argumento o retorno de método) como @NonNull, mientras que la implementación proporciona en realidad un valor anulable. En este caso, una expresión se considera anulable si estáticamente se reconoce que da como resultado el valor null o si se declara con una anotación @Nullable.

En segundo lugar, este grupo también contiene las reglas para la alteración temporal de métodos, como se describía anteriormente. En este caso, un supermétodo establece una alegación (por ejemplo, que null es un argumento permitido), aunque una alteración temporal intenta eludir dicha alegación (presuponiendo que null no es un argumento permitido). Como comentábamos, incluso la especialización de un argumento de no anotado a @NonNull es una violación de especificación, porque incorpora un contrato que debe vincular el cliente (para no pasar un nulo), pero un cliente que utilice el supertipo no verá este contrato, por lo que ni siquiera sabe que se espera de él.

Aquí se proporciona la lista completa de situaciones que se consideran violaciones de especificación. Es importante entender que los errores de este grupo no se deben pasar nunca por alto porque, de lo contrario, todo el análisis de nulos se realizará según asunciones falsas. En concreto, siempre que el compilador ve un valor con una anotación @NonNull, da por hecho que el nulo no aparecerá en tiempo de ejecución. Las reglas sobre las violaciones de especificación son las que garantizan que este razonamiento sea sólido. Por lo tanto, es muy aconsejable que deje este tipo de problema configurado como errores.

Conflicto entre anotaciones de nulos e inferencia de nulos

Además, este grupo de reglas supervisa el cumplimiento de las especificaciones de nulos. No obstante, aquí tenemos que tratar con valores que no se declaran como @Nullable (ni el propio valor null), sino con valores de los que el análisis del flujo dentro del procedimiento infiere que es posible que aparezca un nulo en alguna vía de acceso de ejecución.

Esta situación se plantea porque, para las variables locales no anotadas, el compilador inferirá si un nulo es posible utilizando el análisis de flujo. Presuponiendo que dicho análisis es riguroso, si ve un problema, dicho problema tiene la misma gravedad que las violaciones directas de una especificación de nulos. Por lo tanto, es muy recomendable dejar este problema configurado como error y no pasar por alto estos mensajes.

La creación de un grupo independiente para estos problemas tiene dos finalidades: documentar que se ha planteado un problema determinado con la ayuda del análisis de flujo y explicar el hecho de que este análisis de flujo podría estar en un error (debido a un error en la implementación). En el caso de un error de implementación reconocido, en situaciones excepcionales, podría suprimirse un mensaje de error de este tipo.

Dada la naturaleza de cualquier análisis estático, puede que el análisis de flujo no vea que una combinación concreta de vías de acceso de ejecución y valores no es posible. Como ejemplo, considere la correlación de variables:

   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 aquí
        }
        if (sb1 != null) return sb1.append(sb2).toString();
        return "";
    }

El compilador notificará un acceso de posible puntero nulo en la invocación de sb2.append(..). Una persona puede ver que en realidad no existe ningún peligro porque sb1 y sb2 se correlacionan realmente de manera que las dos son nulas o son no nulas. En la línea en cuestión, sabemos que sb1 no es nula, por lo tanto sb2 no es nula. Sin entrar en los detalles sobre por qué el análisis de correlaciones está fuera del alcance de las prestaciones del compilador Java de Eclipse, recuerde simplemente que este análisis no tiene el potencial de un probador completo de teoremas y que, por lo tanto, notifica de forma pesimista algunos problemas que un análisis más potente podría identificar como falsas alarmas.

Si desea beneficiarse del análisis de flujo, le aconsejamos que ayude un poco al compilador para que pueda "ver" las conclusiones a las que llega. Tal ayuda puede ser simplemente dividir if (sb1 == null) en dos cláusulas if independientes: una para cada variable local, lo que supone un precio muy bajo que pagar por el beneficio que supone que el compilador pueda ver exactamente lo que sucede y comprobar el código de acuerdo con ello. A A continuación de describe con mayor detalle este tema.

Conversión no comprobada de tipo no anotado en tipo @NonNull

Este grupo de problemas se basa en la analogía siguiente: en un programa que utilice genéricos Java 5 las llamadas a bibliotecas anteriores a Java 5 pueden exponer tipos puros, es decir, aplicaciones de un tipo genérico que no pueden especificar argumentos de tipo concreto. Para acomodar dichos valores en un programa mediante genéricos, el compilador puede añadir una conversión implícita presuponiendo que los argumentos de tipo se hayan especificado de la manera que espera la parte de cliente del código. El compilador emitirá un aviso sobre el uso de dicha conversión y proseguirá con su comprobación de tipos presuponiendo que la biblioteca "realiza la acción correcta". Exactamente del mismo modo, un tipo de retorno no anotado de un método de biblioteca se puede considerar como "puro" o "heredado". De nuevo, una conversión implícita puede presuponer de forma optimista la especificación esperada. Se vuelve a emitir un aviso y el análisis sigue presuponiendo que la biblioteca "realiza la acción correcta".

En teoría, la necesidad de dichas conversiones implícitas indica una violación de especificación. No obstante, en este caso, es posible que código de otro proveedor viole la especificación que nuestro código espera. O bien, (tal como nos hemos convencido de ello) quizá código de otro proveedor cumple el contrato, pero no consigue declararlo (porque no utiliza anotaciones de nulos). En tales situaciones, es posible que no podamos corregir el problema por motivos organizativos.

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // conversión implícita
    foo.bar(); 

El fragmento de código anterior presupone que Library.getFoo() devuelve Foo sin especificar una anotación de nulos. Podemos integrar el valor de retorno en nuestro programa anotado mediante la asignación a una variable local @NonNull, que desencadena un aviso sobre una conversión no comprobada. Al añadir un SuppressWarnings("null") correspondiente a esta declaración, reconocemos el peligro inherente y aceptamos la responsabilidad de haber verificado que la biblioteca funciona realmente como se desea.

Consejos para crear código que se pueda analizar mejor

Si el análisis de flujo no puede ver que un valor en realidad no es nulo, la estrategia más sencilla es añadir una variable local nueva con ámbito anotada con @NonNull. A continuación, si está convencido de que el valor asignado a esta variable local no será nunca nulo en tiempo de ejecución, puede utilizar un método de ayuda como el siguiente:

    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, 
                    "El valor no debe ser nulo porque la aplicación" +
                    "está totalmente inicializada en este punto.");
            return theValue;
        }
        return new MyTypeImpl();
    }

Tenga en cuenta que, si utiliza el método assertNonNull() anterior, está aceptando la responsabilidad de que dicha aserción siempre se mantendrá en tiempo de ejecución. Si no es lo que desea, las variables locales anotadas seguirán ayudándole a aislar dónde y por qué el análisis ve un potencia de nulos que fluyen hacia una ubicación determinada.

Consejos para adoptar las anotaciones de nulos

En el momento del lanzamiento de JDT versión 3.8.0, la recopilación de la información sobre consejos para adoptar las anotaciones de nulos aún se está realizando. Por ese motivo, esta información se mantiene actualmente en el wiki de Eclipse.