Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 831c5df6 authored by Tor Norbye's avatar Tor Norbye
Browse files

Add @NotNull, @Nullable, and @IntDef/@StringDef annotations 

This changeset adds some annotations for recording whether a
method return value or method parameter can be null (@Nullable),
can never be null (@NotNull), or must be an integer enum or flag
using one of the given constants.

Change-Id: Ic932592ea3bac781c1df364447c57042461333c5
parent ccd62392

api/current.txt

+6 −0
Original line number Diff line number Diff line
@@ -2592,6 +2592,12 @@ package android.animation { 














package android.annotation {



























  public abstract class NonNull implements java.lang.annotation.Annotation {













  }

























  public abstract class Nullable implements java.lang.annotation.Annotation {













  }



























  public abstract class SuppressLint implements java.lang.annotation.Annotation {















  }







































core/java/android/annotation/IntDef.java
0 → 100644



+65
−0




























Original line number
Diff line number
Diff line













/*













 * Copyright (C) 2013 The Android Open Source Project













 *













 * Licensed under the Apache License, Version 2.0 (the "License");













 * you may not use this file except in compliance with the License.













 * You may obtain a copy of the License at













 *













 *      http://www.apache.org/licenses/LICENSE-2.0













 *













 * Unless required by applicable law or agreed to in writing, software













 * distributed under the License is distributed on an "AS IS" BASIS,













 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.













 * See the License for the specific language governing permissions and













 * limitations under the License.













 */













package android.annotation;



























import java.lang.annotation.Retention;













import java.lang.annotation.RetentionPolicy;













import java.lang.annotation.Target;



























import static java.lang.annotation.ElementType.ANNOTATION_TYPE;













import static java.lang.annotation.ElementType.FIELD;













import static java.lang.annotation.ElementType.METHOD;













import static java.lang.annotation.ElementType.PARAMETER;













import static java.lang.annotation.RetentionPolicy.CLASS;













import static java.lang.annotation.RetentionPolicy.SOURCE;



























/**













 * Denotes that the annotated element of integer type, represents













 * a logical type and that its value should be one of the explicitly













 * named constants. If the {@link #flag()} attribute is set to true,













 * multiple constants can be combined.













 * <p>













 * Example:













 * <pre>{@code













 *  &#64;Retention(CLASS)













 *  &#64;IntDef(&#123;NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS&#125;)













 *  public &#64;interface NavigationMode &#123;&#125;













 *  public static final int NAVIGATION_MODE_STANDARD = 0;













 *  public static final int NAVIGATION_MODE_LIST = 1;













 *  public static final int NAVIGATION_MODE_TABS = 2;













 *  ...













 *  public abstract void setNavigationMode(&#64;NavigationMode int mode);













 *  &#64;NavigationMode













 *  public abstract int getNavigationMode();













 * }</pre>













 * For a flag, set the flag attribute:













 * <pre>{@code













 *  &#64;IntDef(













 *      flag = true













 *      value = &#123;NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS&#125;)













 * }</pre>













 *













 * @hide













 */













@Retention(CLASS)













@Target({ANNOTATION_TYPE})













public @interface IntDef {













    /** Defines the allowed constants for this element */













    long[] value() default {};



























    /** Defines whether the constants can be used as a flag, or just as an enum (the default) */













    boolean flag() default false;













}
























core/java/android/annotation/NonNull.java
0 → 100644



+34
−0




























Original line number
Diff line number
Diff line













/*













 * Copyright (C) 2013 The Android Open Source Project













 *













 * Licensed under the Apache License, Version 2.0 (the "License");













 * you may not use this file except in compliance with the License.













 * You may obtain a copy of the License at













 *













 *      http://www.apache.org/licenses/LICENSE-2.0













 *













 * Unless required by applicable law or agreed to in writing, software













 * distributed under the License is distributed on an "AS IS" BASIS,













 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.













 * See the License for the specific language governing permissions and













 * limitations under the License.













 */













package android.annotation;



























import java.lang.annotation.Retention;













import java.lang.annotation.Target;



























import static java.lang.annotation.ElementType.FIELD;













import static java.lang.annotation.ElementType.METHOD;













import static java.lang.annotation.ElementType.PARAMETER;













import static java.lang.annotation.RetentionPolicy.SOURCE;



























/**













 * Denotes that a parameter, field or method return value can never be null.













 * <p>













 * This is a marker annotation and it has no specific attributes.













 */













@Retention(SOURCE)













@Target({METHOD, PARAMETER, FIELD})













public @interface NonNull {













}
























core/java/android/annotation/Nullable.java
0 → 100644



+41
−0




























Original line number
Diff line number
Diff line













/*













 * Copyright (C) 2013 The Android Open Source Project













 *













 * Licensed under the Apache License, Version 2.0 (the "License");













 * you may not use this file except in compliance with the License.













 * You may obtain a copy of the License at













 *













 *      http://www.apache.org/licenses/LICENSE-2.0













 *













 * Unless required by applicable law or agreed to in writing, software













 * distributed under the License is distributed on an "AS IS" BASIS,













 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.













 * See the License for the specific language governing permissions and













 * limitations under the License.













 */













package android.annotation;



























import java.lang.annotation.Retention;













import java.lang.annotation.Target;



























import static java.lang.annotation.ElementType.FIELD;













import static java.lang.annotation.ElementType.METHOD;













import static java.lang.annotation.ElementType.PARAMETER;













import static java.lang.annotation.RetentionPolicy.SOURCE;



























/**













 * Denotes that a parameter, field or method return value can be null.













 * <p>













 * When decorating a method call parameter, this denotes that the parameter can













 * legitimately be null and the method will gracefully deal with it. Typically













 * used on optional parameters.













 * <p>













 * When decorating a method, this denotes the method might legitimately return













 * null.













 * <p>













 * This is a marker annotation and it has no specific attributes.













 */













@Retention(SOURCE)













@Target({METHOD, PARAMETER, FIELD})













public @interface Nullable {













}
























core/java/android/annotation/StringDef.java
0 → 100644



+55
−0




























Original line number
Diff line number
Diff line













/*













 * Copyright (C) 2013 The Android Open Source Project













 *













 * Licensed under the Apache License, Version 2.0 (the "License");













 * you may not use this file except in compliance with the License.













 * You may obtain a copy of the License at













 *













 *      http://www.apache.org/licenses/LICENSE-2.0













 *













 * Unless required by applicable law or agreed to in writing, software













 * distributed under the License is distributed on an "AS IS" BASIS,













 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.













 * See the License for the specific language governing permissions and













 * limitations under the License.













 */













package android.annotation;



























import java.lang.annotation.Retention;













import java.lang.annotation.Target;



























import static java.lang.annotation.ElementType.ANNOTATION_TYPE;













import static java.lang.annotation.ElementType.FIELD;













import static java.lang.annotation.ElementType.METHOD;













import static java.lang.annotation.ElementType.PARAMETER;













import static java.lang.annotation.RetentionPolicy.CLASS;













import static java.lang.annotation.RetentionPolicy.SOURCE;



























/**













 * Denotes that the annotated String element, represents a logical













 * type and that its value should be one of the explicitly named constants.













 * <p>













 * Example:













 * <pre>{@code













 *  &#64;Retention(SOURCE)













 *  &#64;StringDef(&#123;













 *     POWER_SERVICE,













 *     WINDOW_SERVICE,













 *     LAYOUT_INFLATER_SERVICE













 *  &#125;)













 *  public &#64;interface ServiceName &#123;&#125;













 *  public static final String POWER_SERVICE = "power";













 *  public static final String WINDOW_SERVICE = "window";













 *  public static final String LAYOUT_INFLATER_SERVICE = "layout_inflater";













 *  ...













 *  public abstract Object getSystemService(&#64;ServiceName String name);













 * }</pre>













 *













 * @hide













 */













@Retention(CLASS)













@Target({ANNOTATION_TYPE})













public @interface StringDef {













    /** Defines the allowed constants for this element */













    String[] value() default {};













}