src/org/eclipse/jdt/annotation/NonNull.java

   1 /*******************************************************************************
   2  * Copyright (c) 2011, 2012 Stephan Herrmann and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *     Stephan Herrmann - initial API and implementation
  10  *     IBM Corporation - bug fixes
  11  *******************************************************************************/
  12 package org.eclipse.jdt.annotation;
  13
  14 import static java.lang.annotation.ElementType.LOCAL_VARIABLE;
  15 import static java.lang.annotation.ElementType.METHOD;
  16 import static java.lang.annotation.ElementType.PARAMETER;
  17
  18 import java.lang.annotation.Documented;
  19 import java.lang.annotation.Retention;
  20 import java.lang.annotation.RetentionPolicy;
  21 import java.lang.annotation.Target;
  22
  23 /**
  24  * Qualifier for a type in a method signature or a local variable declaration:
  25  * The entity (return value, parameter, local variable) whose type has this
  26  * annotation can never have the value <code>null</code> at runtime.
  27  * <p>
  28  * This has two consequences:
  29  * <ol>
  30  * <li>Dereferencing the entity is safe, i.e., no <code>NullPointerException</code> can occur at runtime.</li>
  31  * <li>An attempt to bind a <code>null</code> value to the entity is a compile time error.</li>
  32  * </ol>
  33  * For the second case, diagnostics issued by the compiler should distinguish three situations:
  34  * <ol>
  35  * <li>Nullness of the value can be statically determined, the entity is definitely bound from either of:
  36  *     <ul><li>the value <code>null</code>, or</li>
  37  *         <li>an entity with a {@link Nullable @Nullable} type.</li></ul></li>
  38  * <li>Nullness cannot definitely be determined, because different code branches yield different results.</li>
  39  * <li>Nullness cannot be determined, because other program elements are involved for which
  40  *     null annotations are lacking.</li>
  41  * </ol>
  42  * </p>
  43  * @since 1.0
  44  */
  45 @Documented
  46 @Retention(RetentionPolicy.CLASS)
  47 @Target({ METHOD, PARAMETER, LOCAL_VARIABLE })
  48 public @interface NonNull {
  49         // marker annotation with no members
  50 }