Java: use la anotación NotNull en el argumento del método

Use @NotNull en un argumento de método de tipo referencia para indicar que se espera que quien llama proporcione un valor. La anotación expresa un contrato, pero por sí sola no rechaza null ni ejecuta una validación. Este ejemplo muestra la declaración y explica qué implica aplicar ese contrato mediante un mecanismo adicional.

¿Qué es la anotación @NotNull?

@NotNull es una anotación que usan las bibliotecas de Java para indicar que se espera que un valor no sea nulo. Puede hacer más visible el contrato de una API en el código fuente, la documentación y las herramientas que reconocen esa anotación concreta. El paquete y el comportamiento exactos dependen de la biblioteca que la proporcione; por eso, use la anotación compatible con su proyecto y no dé por hecho que todas las anotaciones @NotNull se implementan igual.

La declaración de una anotación no modifica el sistema de tipos de Java ni impide que una variable contenga null. Tampoco garantiza que un método devuelva un valor no nulo ni que pasarle null provoque una excepción. Para validar el valor anotado en tiempo de ejecución hace falta un mecanismo independiente, configurado para inspeccionarlo o validarlo; ese mecanismo y su comportamiento quedan fuera de este ejemplo, que solo muestra una declaración.

La principal ventaja es que facilita la comunicación entre quien escribe el método y quienes lo llaman. Un contrato visible de valor no nulo ayuda a entender qué entrada se espera y puede ser compatible con herramientas de análisis estático o de frameworks. Sirve como documentación, pero no sustituye la comprobación de entradas cuando la aplicación necesita aplicar esa restricción.

Cómo usar @NotNull en los argumentos de métodos

Coloque la anotación justo antes de un parámetro de tipo referencia, como String. El siguiente ejemplo muestra únicamente una declaración; elija el import y la biblioteca que utilice su proyecto:

public void createUser(@NotNull String username) { ... }

Aquí, username es el argumento del método y @NotNull expresa que se espera que quien lo llame proporcione una cadena no nula. String es un tipo referencia y, por tanto, puede recibir null en Java salvo que una comprobación aparte o un mecanismo configurado lo rechace. Los tipos primitivos, como int, no pueden recibir null, así que no sirven para ilustrar este contrato.

Si el proyecto necesita validar ese contrato en tiempo de ejecución, configure y utilice un mecanismo compatible con la anotación elegida. Añadir el import de una anotación o escribirla en el parámetro no realiza la validación. La declaración anterior no está asociada a ninguna dependencia, proveedor, forma de invocación ni resultado en tiempo de ejecución; esas decisiones dependen del proyecto y no se muestran aquí.

Use el contrato para que la intención sea más fácil de revisar y mantener. Quienes llamen al método deberían proporcionar un nombre de usuario válido, y el método aún puede comprobar sus propias entradas cuando la aplicación lo requiera. Mantenga coherente el paquete de la anotación en todo el código, ya que varias bibliotecas pueden ofrecer anotaciones con el mismo nombre simple y distinto soporte para herramientas.