org.eclipse.jdt.annotation.NonNullByDefault Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jdt.annotation Show documentation

JDT Annotations for Enhanced Null Analysis

There is a newer version: 2.3.0

Show newest version

/*******************************************************************************
 * Copyright (c) 2011, 2014 Stephan Herrmann and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     Stephan Herrmann - initial API and implementation
 *     IBM Corporation - bug fixes
 *******************************************************************************/
package org.eclipse.jdt.annotation;

import java.lang.annotation.ElementType;
import static org.eclipse.jdt.annotation.DefaultLocation.*;

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

/**
 * Applying this annotation to a declaration has the effect that type references,
 * which are contained in the declaration, and for which a null annotation is otherwise lacking,
 * should be considered as {@link NonNull @NonNull}.
 * 
 * Locations
 * This annotation is permitted for these declarations:
 * {@link ElementType#PACKAGE PACKAGE}, {@link ElementType#TYPE TYPE},
 * {@link ElementType#METHOD METHOD}, {@link ElementType#CONSTRUCTOR CONSTRUCTOR},
 * {@link ElementType#FIELD FIELD}, {@link ElementType#LOCAL_VARIABLE LOCAL_VARIABLE}.
 * Fine tuning
 * The exact effect is further controlled by the attribute {@link #value}, specifying what
 * kinds of locations within the given declaration will be affected. See {@link DefaultLocation}
 * for the meaning of the available values.
 * Nested defaults
 * If this annotation is applied to a declaration that is already affected by the same
 * annotation at an enclosing scope, the inner annotation replaces the effect of the
 * outer annotation for the scope of the inner declaration.
 * Canceling a default
 * In particular, specifying an empty value ({}) for the {@link #value}
 * attribute has the effect of canceling any null defaults that might be defined for any
 * enclosing scope.
 * 
 * 
 * Note that for applying an annotation to a package, a file by the name
 * package-info.java is used.
 * 
 * 
 * Note: Since org.eclipse.jdt.annotation 2.0.0, this annotation also applies to field and
 * local variable declarations and since 2.2.0 also to parameter and module declarations.
 * For the old API, see
 * 
 * @NonNullByDefault in 1.1.0.
 * 
 * @since 1.0
 */
@Documented
@Retention(RetentionPolicy.CLASS)
public @interface NonNullByDefault {
	/**
	 * Specifies the set of locations within the annotated declaration that should be affected by the nonnull default.
	 * @return the locations, or an empty array to cancel any null defaults from enclosing scopes
	 * @since 2.0
	 */
	DefaultLocation[] value() default { PARAMETER, RETURN_TYPE, FIELD, TYPE_BOUND, TYPE_ARGUMENT };
}