interface @Optional

Optionality marker annotation. Method arguments are required by default in Qi4j, and this annotation declares that the argument may optionally be null.

Description

If a method parameter is not marked with this annotation, there will be an validation exception thrown if you try to pass a null argument for that method parameter.

The authors od Qi4j have noticed that a large number of software bugs are related to the null argument. By disallowing it by default, and required the developer to indicate that optionality is handled explicitly in the code, Qi4j applications becomes inherently more robust, catching null problems early.

Declaration

package org.qi4j.api.common;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
* Annotation to denote that a method parameter
* is optional, i.e. it can be null. Default
* is that method parameters have to be non-null.
*/
@Retention( RetentionPolicy.RUNTIME )
@Target( { ElementType.PARAMETER, ElementType.METHOD } )
@Documented
public @interface Optional
{
}

Example

In the following code, the client will succeed with the first() method call, but not the second, since the latter method parameter is not declared optional.
public interface SomeType
{
    void first( @Optional String arg );
    void second( String arg );
}

SomeType some = ...;

some.first( null );  // Will succeed.

some.second( null );  // Exception will be thrown.


Qi4j and the Qi4j logo are trademarks of Richard Öberg, Niclas Hedhman and the members of the Qi4j Core Team. See Qi4j licensing for more information.
Powered by SiteVisionexternal link.