am 77545f6a: Merge "Camera2: Add SDK annotations" into mnc-dev

* commit '77545f6a19bda0d22e946497f29a8d191d68c212':
  Camera2: Add SDK annotations

core/java/android/hardware/camera2/CameraAccessException.java

@@ -16,8 +16,13 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
+import android.annotation.IntDef;
 import android.util.AndroidException;
 
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
 /**
  * <p><code>CameraAccessException</code> is thrown if a camera device could not
  * be queried or opened by the {@link CameraManager}, or if the connection to an
@@ -76,6 +81,16 @@ public class CameraAccessException extends AndroidException {
      */
     public static final int CAMERA_DEPRECATED_HAL = 1000;
 
+     /** @hide */
+     @Retention(RetentionPolicy.SOURCE)
+     @IntDef(
+         {CAMERA_IN_USE,
+          MAX_CAMERAS_IN_USE,
+          CAMERA_DISABLED,
+          CAMERA_DISCONNECTED,
+          CAMERA_ERROR})
+     public @interface AccessError {};
+
     // Make the eclipse warning about serializable exceptions go away
     private static final long serialVersionUID = 5630338637471475675L; // randomly generated
 
@@ -88,26 +103,27 @@ public class CameraAccessException extends AndroidException {
      * @see #CAMERA_DISCONNECTED
      * @see #CAMERA_ERROR
      */
+    @AccessError
     public final int getReason() {
         return mReason;
     }
 
-    public CameraAccessException(int problem) {
+    public CameraAccessException(@AccessError int problem) {
         super(getDefaultMessage(problem));
         mReason = problem;
     }
 
-    public CameraAccessException(int problem, String message) {
+    public CameraAccessException(@AccessError int problem, String message) {
         super(message);
         mReason = problem;
     }
 
-    public CameraAccessException(int problem, String message, Throwable cause) {
+    public CameraAccessException(@AccessError int problem, String message, Throwable cause) {
         super(message, cause);
         mReason = problem;
     }
 
-    public CameraAccessException(int problem, Throwable cause) {
+    public CameraAccessException(@AccessError int problem, Throwable cause) {
         super(getDefaultMessage(problem), cause);
         mReason = problem;
     }
@@ -115,7 +131,7 @@ public class CameraAccessException extends AndroidException {
     /**
      * @hide
      */
-    public static String getDefaultMessage(int problem) {
+    public static String getDefaultMessage(@AccessError int problem) {
         switch (problem) {
             case CAMERA_IN_USE:
                 return "The camera device is in use already";

core/java/android/hardware/camera2/CameraCaptureSession.java

@@ -16,6 +16,8 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.os.Handler;
 import android.view.Surface;
 
@@ -73,6 +75,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
     /**
      * Get the camera device that this session is created for.
      */
+    @NonNull
     public abstract CameraDevice getDevice();
 
     /**
@@ -133,7 +136,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      *
      * @see StateCallback#onSurfacePrepared
      */
-    public abstract void prepare(Surface surface) throws CameraAccessException;
+    public abstract void prepare(@NonNull Surface surface) throws CameraAccessException;
 
     /**
      * <p>Submit a request for an image to be captured by the camera device.</p>
@@ -194,7 +197,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      * @see #abortCaptures
      * @see CameraDevice#createReprocessableCaptureSession
      */
-    public abstract int capture(CaptureRequest request, CaptureCallback listener, Handler handler)
+    public abstract int capture(@NonNull CaptureRequest request,
+            @Nullable CaptureCallback listener, @Nullable Handler handler)
             throws CameraAccessException;
 
     /**
@@ -252,8 +256,9 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      * @see #setRepeatingBurst
      * @see #abortCaptures
      */
-    public abstract int captureBurst(List<CaptureRequest> requests, CaptureCallback listener,
+    public abstract int captureBurst(@NonNull List<CaptureRequest> requests,
-            Handler handler) throws CameraAccessException;
+            @Nullable CaptureCallback listener, @Nullable Handler handler)
+            throws CameraAccessException;
 
     /**
      * Request endlessly repeating capture of images by this capture session.
@@ -318,8 +323,9 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      * @see #stopRepeating
      * @see #abortCaptures
      */
-    public abstract int setRepeatingRequest(CaptureRequest request, CaptureCallback listener,
+    public abstract int setRepeatingRequest(@NonNull CaptureRequest request,
-            Handler handler) throws CameraAccessException;
+            @Nullable CaptureCallback listener, @Nullable Handler handler)
+            throws CameraAccessException;
 
     /**
      * <p>Request endlessly repeating capture of a sequence of images by this
@@ -389,8 +395,9 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      * @see #stopRepeating
      * @see #abortCaptures
      */
-    public abstract int setRepeatingBurst(List<CaptureRequest> requests, CaptureCallback listener,
+    public abstract int setRepeatingBurst(@NonNull List<CaptureRequest> requests,
-            Handler handler) throws CameraAccessException;
+            @Nullable CaptureCallback listener, @Nullable Handler handler)
+            throws CameraAccessException;
 
     /**
      * <p>Cancel any ongoing repeating capture set by either
@@ -478,6 +485,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      * @see android.media.ImageWriter
      * @see android.media.ImageReader
      */
+    @Nullable
     public abstract Surface getInputSurface();
 
     /**
@@ -525,7 +533,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          *
          * @param session the session returned by {@link CameraDevice#createCaptureSession}
          */
-        public abstract void onConfigured(CameraCaptureSession session);
+        public abstract void onConfigured(@NonNull CameraCaptureSession session);
 
         /**
          * This method is called if the session cannot be configured as requested.
@@ -540,7 +548,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          *
          * @param session the session returned by {@link CameraDevice#createCaptureSession}
          */
-        public abstract void onConfigureFailed(CameraCaptureSession session);
+        public abstract void onConfigureFailed(@NonNull CameraCaptureSession session);
 
         /**
          * This method is called every time the session has no more capture requests to process.
@@ -555,7 +563,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          * @param session the session returned by {@link CameraDevice#createCaptureSession}
          *
          */
-        public void onReady(CameraCaptureSession session) {
+        public void onReady(@NonNull CameraCaptureSession session) {
             // default empty implementation
         }
 
@@ -571,7 +579,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          *
          * @param session the session returned by {@link CameraDevice#createCaptureSession}
          */
-        public void onActive(CameraCaptureSession session) {
+        public void onActive(@NonNull CameraCaptureSession session) {
             // default empty implementation
         }
 
@@ -589,7 +597,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          *
          * @param session the session returned by {@link CameraDevice#createCaptureSession}
          */
-        public void onClosed(CameraCaptureSession session) {
+        public void onClosed(@NonNull CameraCaptureSession session) {
             // default empty implementation
         }
 
@@ -608,7 +616,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          * @param session the session returned by {@link CameraDevice#createCaptureSession}
          * @param surface the Surface that was used with the {@link #prepare} call.
          */
-        public void onSurfacePrepared(CameraCaptureSession session, Surface surface) {
+        public void onSurfacePrepared(@NonNull CameraCaptureSession session,
+                @NonNull Surface surface) {
             // default empty implementation
         }
     }
@@ -675,8 +684,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          *
          * @see android.media.MediaActionSound
          */
-        public void onCaptureStarted(CameraCaptureSession session,
+        public void onCaptureStarted(@NonNull CameraCaptureSession session,
-                CaptureRequest request, long timestamp, long frameNumber) {
+                @NonNull CaptureRequest request, long timestamp, long frameNumber) {
             // Temporary trampoline for API change transition
             onCaptureStarted(session, request, timestamp);
         }
@@ -756,8 +765,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          * @see #setRepeatingRequest
          * @see #setRepeatingBurst
          */
-        public void onCaptureProgressed(CameraCaptureSession session,
+        public void onCaptureProgressed(@NonNull CameraCaptureSession session,
-                CaptureRequest request, CaptureResult partialResult) {
+                @NonNull CaptureRequest request, @NonNull CaptureResult partialResult) {
             // default empty implementation
         }
 
@@ -785,8 +794,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          * @see #setRepeatingRequest
          * @see #setRepeatingBurst
          */
-        public void onCaptureCompleted(CameraCaptureSession session,
+        public void onCaptureCompleted(@NonNull CameraCaptureSession session,
-                CaptureRequest request, TotalCaptureResult result) {
+                @NonNull CaptureRequest request, @NonNull TotalCaptureResult result) {
             // default empty implementation
         }
 
@@ -814,8 +823,8 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          * @see #setRepeatingRequest
          * @see #setRepeatingBurst
          */
-        public void onCaptureFailed(CameraCaptureSession session,
+        public void onCaptureFailed(@NonNull CameraCaptureSession session,
-                CaptureRequest request, CaptureFailure failure) {
+                @NonNull CaptureRequest request, @NonNull CaptureFailure failure) {
             // default empty implementation
         }
 
@@ -844,7 +853,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          * @see CaptureFailure#getSequenceId()
          * @see #onCaptureSequenceAborted
          */
-        public void onCaptureSequenceCompleted(CameraCaptureSession session,
+        public void onCaptureSequenceCompleted(@NonNull CameraCaptureSession session,
                 int sequenceId, long frameNumber) {
             // default empty implementation
         }
@@ -873,7 +882,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          * @see CaptureFailure#getSequenceId()
          * @see #onCaptureSequenceCompleted
          */
-        public void onCaptureSequenceAborted(CameraCaptureSession session,
+        public void onCaptureSequenceAborted(@NonNull CameraCaptureSession session,
                 int sequenceId) {
             // default empty implementation
         }

core/java/android/hardware/camera2/CameraCharacteristics.java

@@ -16,6 +16,8 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.hardware.camera2.impl.CameraMetadataNative;
 import android.hardware.camera2.impl.PublicKey;
 import android.hardware.camera2.impl.SyntheticKey;
@@ -91,6 +93,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
          *
          * @return String representation of the key name
          */
+        @NonNull
         public String getName() {
             return mKey.getName();
         }
@@ -166,6 +169,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
      * @param key The characteristics field to read.
      * @return The value of that key, or {@code null} if the field is not set.
      */
+    @Nullable
     public <T> T get(Key<T> key) {
         return mProperties.get(key);
     }
@@ -194,6 +198,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
     /**
      * {@inheritDoc}
      */
+    @NonNull
     @Override
     public List<Key<?>> getKeys() {
         // List of keys is immutable; cache the results after we calculate them
@@ -227,6 +232,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
      * @return List of keys supported by this CameraDevice for CaptureRequests.
      */
     @SuppressWarnings({"unchecked"})
+    @NonNull
     public List<CaptureRequest.Key<?>> getAvailableCaptureRequestKeys() {
         if (mAvailableRequestKeys == null) {
             Object crKey = CaptureRequest.Key.class;
@@ -258,6 +264,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
      * @return List of keys supported by this CameraDevice for CaptureResults.
      */
     @SuppressWarnings({"unchecked"})
+    @NonNull
     public List<CaptureResult.Key<?>> getAvailableCaptureResultKeys() {
         if (mAvailableResultKeys == null) {
             Object crKey = CaptureResult.Key.class;

core/java/android/hardware/camera2/CameraDevice.java

@@ -16,6 +16,9 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+import android.annotation.IntDef;
 import android.hardware.camera2.params.InputConfiguration;
 import android.hardware.camera2.params.StreamConfigurationMap;
 import android.hardware.camera2.params.OutputConfiguration;
@@ -23,6 +26,8 @@ import android.os.Handler;
 import android.view.Surface;
 
 import java.util.List;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 
 /**
  * <p>The CameraDevice class is a representation of a single camera connected to an
@@ -124,6 +129,17 @@ public abstract class CameraDevice implements AutoCloseable {
      */
     public static final int TEMPLATE_MANUAL = 6;
 
+     /** @hide */
+     @Retention(RetentionPolicy.SOURCE)
+     @IntDef(
+         {TEMPLATE_PREVIEW,
+          TEMPLATE_STILL_CAPTURE,
+          TEMPLATE_RECORD,
+          TEMPLATE_VIDEO_SNAPSHOT,
+          TEMPLATE_ZERO_SHUTTER_LAG,
+          TEMPLATE_MANUAL })
+     public @interface RequestTemplate {};
+
     /**
      * Get the ID of this camera device.
      *
@@ -142,6 +158,7 @@ public abstract class CameraDevice implements AutoCloseable {
      * @see CameraManager#getCameraCharacteristics
      * @see CameraManager#getCameraIdList
      */
+    @NonNull
     public abstract String getId();
 
     /**
@@ -391,8 +408,8 @@ public abstract class CameraDevice implements AutoCloseable {
      * @see StreamConfigurationMap#getOutputSizes(int)
      * @see StreamConfigurationMap#getOutputSizes(Class)
      */
-    public abstract void createCaptureSession(List<Surface> outputs,
+    public abstract void createCaptureSession(@NonNull List<Surface> outputs,
-            CameraCaptureSession.StateCallback callback, Handler handler)
+            @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)
             throws CameraAccessException;
 
     /**
@@ -560,8 +577,9 @@ public abstract class CameraDevice implements AutoCloseable {
      * @see android.media.ImageWriter
      * @see android.media.ImageReader
      */
-    public abstract void createReprocessableCaptureSession(InputConfiguration inputConfig,
+    public abstract void createReprocessableCaptureSession(@NonNull InputConfiguration inputConfig,
-            List<Surface> outputs, CameraCaptureSession.StateCallback callback, Handler handler)
+            @NonNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback,
+            @Nullable Handler handler)
             throws CameraAccessException;
 
     /**
@@ -591,7 +609,8 @@ public abstract class CameraDevice implements AutoCloseable {
      * @see #TEMPLATE_VIDEO_SNAPSHOT
      * @see #TEMPLATE_MANUAL
      */
-    public abstract CaptureRequest.Builder createCaptureRequest(int templateType)
+    @NonNull
+    public abstract CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType)
             throws CameraAccessException;
 
     /**
@@ -620,8 +639,9 @@ public abstract class CameraDevice implements AutoCloseable {
      * @see CameraDevice#createReprocessableCaptureSession
      * @see android.media.ImageWriter
      */
+    @NonNull
     public abstract CaptureRequest.Builder createReprocessCaptureRequest(
-            TotalCaptureResult inputResult) throws CameraAccessException;
+            @NonNull TotalCaptureResult inputResult) throws CameraAccessException;
 
     /**
      * Close the connection to this camera device as quickly as possible.
@@ -727,6 +747,16 @@ public abstract class CameraDevice implements AutoCloseable {
          */
         public static final int ERROR_CAMERA_SERVICE = 5;
 
+        /** @hide */
+        @Retention(RetentionPolicy.SOURCE)
+        @IntDef(
+            {ERROR_CAMERA_IN_USE,
+             ERROR_MAX_CAMERAS_IN_USE,
+             ERROR_CAMERA_DISABLED,
+             ERROR_CAMERA_DEVICE,
+             ERROR_CAMERA_SERVICE })
+        public @interface ErrorCode {};
+
         /**
          * The method called when a camera device has finished opening.
          *
@@ -736,7 +766,7 @@ public abstract class CameraDevice implements AutoCloseable {
          *
          * @param camera the camera device that has become opened
          */
-        public abstract void onOpened(CameraDevice camera); // Must implement
+        public abstract void onOpened(@NonNull CameraDevice camera); // Must implement
 
         /**
          * The method called when a camera device has been closed with
@@ -749,7 +779,7 @@ public abstract class CameraDevice implements AutoCloseable {
          *
          * @param camera the camera device that has become closed
          */
-        public void onClosed(CameraDevice camera) {
+        public void onClosed(@NonNull CameraDevice camera) {
             // Default empty implementation
         }
 
@@ -781,7 +811,7 @@ public abstract class CameraDevice implements AutoCloseable {
          *
          * @param camera the device that has been disconnected
          */
-        public abstract void onDisconnected(CameraDevice camera); // Must implement
+        public abstract void onDisconnected(@NonNull CameraDevice camera); // Must implement
 
         /**
          * The method called when a camera device has encountered a serious error.
@@ -805,12 +835,14 @@ public abstract class CameraDevice implements AutoCloseable {
          * @param error The error code, one of the
          *     {@code StateCallback.ERROR_*} values.
          *
+         * @see #ERROR_CAMERA_IN_USE
+         * @see #ERROR_MAX_CAMERAS_IN_USE
+         * @see #ERROR_CAMERA_DISABLED
          * @see #ERROR_CAMERA_DEVICE
          * @see #ERROR_CAMERA_SERVICE
-         * @see #ERROR_CAMERA_DISABLED
-         * @see #ERROR_CAMERA_IN_USE
          */
-        public abstract void onError(CameraDevice camera, int error); // Must implement
+        public abstract void onError(@NonNull CameraDevice camera,
+                @ErrorCode int error); // Must implement
     }
 
     /**

core/java/android/hardware/camera2/CameraManager.java

@@ -16,6 +16,9 @@
 
 package android.hardware.camera2;
 
+import android.annotation.RequiresPermission;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.content.Context;
 import android.hardware.ICameraService;
 import android.hardware.ICameraServiceListener;
@@ -86,6 +89,7 @@ public final class CameraManager {
      *
      * @return The list of currently connected camera devices.
      */
+    @NonNull
     public String[] getCameraIdList() throws CameraAccessException {
         synchronized (mLock) {
             // ID list creation handles various known failures in device enumeration, so only
@@ -121,7 +125,8 @@ public final class CameraManager {
      * @throws IllegalArgumentException if the handler is {@code null} but the current thread has
      *             no looper.
      */
-    public void registerAvailabilityCallback(AvailabilityCallback callback, Handler handler) {
+    public void registerAvailabilityCallback(@NonNull AvailabilityCallback callback,
+            @Nullable Handler handler) {
         if (handler == null) {
             Looper looper = Looper.myLooper();
             if (looper == null) {
@@ -142,7 +147,7 @@ public final class CameraManager {
      *
      * @param callback The callback to remove from the notification list
      */
-    public void unregisterAvailabilityCallback(AvailabilityCallback callback) {
+    public void unregisterAvailabilityCallback(@NonNull AvailabilityCallback callback) {
         CameraManagerGlobal.get().unregisterAvailabilityCallback(callback);
     }
 
@@ -168,7 +173,7 @@ public final class CameraManager {
      * @throws IllegalArgumentException if the handler is {@code null} but the current thread has
      *             no looper.
      */
-    public void registerTorchCallback(TorchCallback callback, Handler handler) {
+    public void registerTorchCallback(@NonNull TorchCallback callback, @Nullable Handler handler) {
         if (handler == null) {
             Looper looper = Looper.myLooper();
             if (looper == null) {
@@ -188,7 +193,7 @@ public final class CameraManager {
      *
      * @param callback The callback to remove from the notification list
      */
-    public void unregisterTorchCallback(TorchCallback callback) {
+    public void unregisterTorchCallback(@NonNull TorchCallback callback) {
         CameraManagerGlobal.get().unregisterTorchCallback(callback);
     }
 
@@ -201,15 +206,13 @@ public final class CameraManager {
      *
      * @throws IllegalArgumentException if the cameraId does not match any
      *         known camera device.
-     * @throws CameraAccessException if the camera is disabled by device policy, or
+     * @throws CameraAccessException if the camera device has been disconnected.
-     *         the camera device has been disconnected.
-     * @throws SecurityException if the application does not have permission to
-     *         access the camera
      *
      * @see #getCameraIdList
      * @see android.app.admin.DevicePolicyManager#setCameraDisabled
      */
-    public CameraCharacteristics getCameraCharacteristics(String cameraId)
+    @NonNull
+    public CameraCharacteristics getCameraCharacteristics(@NonNull String cameraId)
             throws CameraAccessException {
         CameraCharacteristics characteristics = null;
 
@@ -431,8 +434,9 @@ public final class CameraManager {
      * @see #getCameraIdList
      * @see android.app.admin.DevicePolicyManager#setCameraDisabled
      */
-    public void openCamera(String cameraId, final CameraDevice.StateCallback callback,
+    @RequiresPermission(android.Manifest.permission.CAMERA)
-            Handler handler)
+    public void openCamera(@NonNull String cameraId,
+            @NonNull final CameraDevice.StateCallback callback, @Nullable Handler handler)
             throws CameraAccessException {
 
         if (cameraId == null) {
@@ -444,7 +448,7 @@ public final class CameraManager {
                 handler = new Handler();
             } else {
                 throw new IllegalArgumentException(
-                        "Looper doesn't exist in the calling thread");
+                        "Handler argument is null, but no looper exists in the calling thread");
             }
         }
 
@@ -490,7 +494,8 @@ public final class CameraManager {
      *             or previously available camera device, or the camera device doesn't have a
      *             flash unit.
      */
-    public void setTorchMode(String cameraId, boolean enabled) throws CameraAccessException {
+    public void setTorchMode(@NonNull String cameraId, boolean enabled)
+            throws CameraAccessException {
         CameraManagerGlobal.get().setTorchMode(cameraId, enabled);
     }
 
@@ -517,7 +522,7 @@ public final class CameraManager {
          *
          * @param cameraId The unique identifier of the new camera.
          */
-        public void onCameraAvailable(String cameraId) {
+        public void onCameraAvailable(@NonNull String cameraId) {
             // default empty implementation
         }
 
@@ -532,7 +537,7 @@ public final class CameraManager {
          *
          * @param cameraId The unique identifier of the disconnected camera.
          */
-        public void onCameraUnavailable(String cameraId) {
+        public void onCameraUnavailable(@NonNull String cameraId) {
             // default empty implementation
         }
     }
@@ -572,7 +577,7 @@ public final class CameraManager {
          * @param cameraId The unique identifier of the camera whose torch mode has become
          *                 unavailable.
          */
-        public void onTorchModeUnavailable(String cameraId) {
+        public void onTorchModeUnavailable(@NonNull String cameraId) {
             // default empty implementation
         }
 
@@ -589,7 +594,7 @@ public final class CameraManager {
          *                off. {@code false} when the torch mode has becomes off and available to
          *                be turned on.
          */
-        public void onTorchModeChanged(String cameraId, boolean enabled) {
+        public void onTorchModeChanged(@NonNull String cameraId, boolean enabled) {
             // default empty implementation
         }
     }

core/java/android/hardware/camera2/CameraMetadata.java

@@ -16,6 +16,7 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
 import android.hardware.camera2.impl.CameraMetadataNative;
 import android.hardware.camera2.impl.PublicKey;
 import android.hardware.camera2.impl.SyntheticKey;
@@ -103,6 +104,7 @@ public abstract class CameraMetadata<TKey> {
      * @return List of the keys contained in this map.
      */
     @SuppressWarnings("unchecked")
+    @NonNull
     public List<TKey> getKeys() {
         Class<CameraMetadata<TKey>> thisClass = (Class<CameraMetadata<TKey>>) getClass();
         return Collections.unmodifiableList(

core/java/android/hardware/camera2/CaptureFailure.java

@@ -15,6 +15,12 @@
  */
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
+import android.annotation.IntDef;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
 /**
  * A report of failed capture for a single image capture from the image sensor.
  *
@@ -43,6 +49,13 @@ public class CaptureFailure {
      */
     public static final int REASON_FLUSHED = 1;
 
+     /** @hide */
+     @Retention(RetentionPolicy.SOURCE)
+     @IntDef(
+         {REASON_ERROR,
+          REASON_FLUSHED })
+     public @interface FailureReason {};
+
     private final CaptureRequest mRequest;
     private final int mReason;
     private final boolean mDropped;
@@ -52,8 +65,8 @@ public class CaptureFailure {
     /**
      * @hide
      */
-    public CaptureFailure(CaptureRequest request, int reason, boolean dropped, int sequenceId,
+    public CaptureFailure(CaptureRequest request, int reason,
-            long frameNumber) {
+            boolean dropped, int sequenceId, long frameNumber) {
         mRequest = request;
         mReason = reason;
         mDropped = dropped;
@@ -81,6 +94,7 @@ public class CaptureFailure {
      *
      * @return The request associated with this failed capture. Never {@code null}.
      */
+    @NonNull
     public CaptureRequest getRequest() {
         return mRequest;
     }
@@ -110,6 +124,7 @@ public class CaptureFailure {
      * @see #REASON_ERROR
      * @see #REASON_FLUSHED
      */
+    @FailureReason
     public int getReason() {
         return mReason;
     }

core/java/android/hardware/camera2/CaptureRequest.java

@@ -16,6 +16,8 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.hardware.camera2.impl.CameraMetadataNative;
 import android.hardware.camera2.impl.PublicKey;
 import android.hardware.camera2.impl.SyntheticKey;
@@ -117,6 +119,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          *
          * @return String representation of the key name
          */
+        @NonNull
         public String getName() {
             return mKey.getName();
         }
@@ -239,6 +242,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      * @param key The result field to read.
      * @return The value of that key, or {@code null} if the field is not set.
      */
+    @Nullable
     public <T> T get(Key<T> key) {
         return mSettings.get(key);
     }
@@ -268,6 +272,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      * {@inheritDoc}
      */
     @Override
+    @NonNull
     public List<Key<?>> getKeys() {
         // Force the javadoc for this function to show up on the CaptureRequest page
         return super.getKeys();
@@ -286,6 +291,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      *     no tag has been set.
      * @see Builder#setTag
      */
+    @Nullable
     public Object getTag() {
         return mUserTag;
     }
@@ -476,7 +482,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          *
          * @param outputTarget Surface to use as an output target for this request
          */
-        public void addTarget(Surface outputTarget) {
+        public void addTarget(@NonNull Surface outputTarget) {
             mRequest.mSurfaceSet.add(outputTarget);
         }
 
@@ -487,7 +493,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          *
          * @param outputTarget Surface to use as an output target for this request
          */
-        public void removeTarget(Surface outputTarget) {
+        public void removeTarget(@NonNull Surface outputTarget) {
             mRequest.mSurfaceSet.remove(outputTarget);
         }
 
@@ -499,7 +505,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          * @param value The value to set the field to, which must be of a matching
          * type to the key.
          */
-        public <T> void set(Key<T> key, T value) {
+        public <T> void set(@NonNull Key<T> key, T value) {
             mRequest.mSettings.set(key, value);
         }
 
@@ -512,6 +518,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          * @param key The metadata field to read.
          * @return The value of that key, or {@code null} if the field is not set.
          */
+        @Nullable
         public <T> T get(Key<T> key) {
             return mRequest.mSettings.get(key);
         }
@@ -527,7 +534,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          * @param tag an arbitrary Object to store with this request
          * @see CaptureRequest#getTag
          */
-        public void setTag(Object tag) {
+        public void setTag(@Nullable Object tag) {
             mRequest.mUserTag = tag;
         }
 
@@ -543,6 +550,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          * @return A new capture request instance, ready for submission to the
          * camera device.
          */
+        @NonNull
         public CaptureRequest build() {
             return new CaptureRequest(mRequest);
         }

core/java/android/hardware/camera2/CaptureResult.java

@@ -16,6 +16,8 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.hardware.camera2.impl.CameraMetadataNative;
 import android.hardware.camera2.impl.CaptureResultExtras;
 import android.hardware.camera2.impl.PublicKey;
@@ -102,6 +104,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
          *
          * @return String representation of the key name
          */
+        @NonNull
         public String getName() {
             return mKey.getName();
         }
@@ -216,6 +219,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * @param key The result field to read.
      * @return The value of that key, or {@code null} if the field is not set.
      */
+    @Nullable
     public <T> T get(Key<T> key) {
         T value = mResults.get(key);
         if (VERBOSE) Log.v(TAG, "#get for Key = " + key.getName() + ", returned value = " + value);
@@ -259,6 +263,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * {@inheritDoc}
      */
     @Override
+    @NonNull
     public List<Key<?>> getKeys() {
         // Force the javadoc for this function to show up on the CaptureResult page
         return super.getKeys();
@@ -285,6 +290,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      *
      * @return The request associated with this result. Never {@code null}.
      */
+    @NonNull
     public CaptureRequest getRequest() {
         return mRequest;
     }

core/java/android/hardware/camera2/DngCreator.java

@@ -16,6 +16,9 @@
 
 package android.hardware.camera2;
 
+import android.annotation.IntRange;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.graphics.Bitmap;
 import android.graphics.Color;
 import android.graphics.ImageFormat;
@@ -80,7 +83,8 @@ public final class DngCreator implements AutoCloseable {
      *          {@link android.hardware.camera2.CameraCharacteristics}.
      * @param metadata a metadata object to generate tags from.
      */
-    public DngCreator(CameraCharacteristics characteristics, CaptureResult metadata) {
+    public DngCreator(@NonNull CameraCharacteristics characteristics,
+            @NonNull CaptureResult metadata) {
         if (characteristics == null || metadata == null) {
             throw new IllegalArgumentException("Null argument to DngCreator constructor");
         }
@@ -126,6 +130,7 @@ public final class DngCreator implements AutoCloseable {
      *                    </ul>
      * @return this {@link #DngCreator} object.
      */
+    @NonNull
     public DngCreator setOrientation(int orientation) {
         if (orientation < ExifInterface.ORIENTATION_UNDEFINED ||
                 orientation > ExifInterface.ORIENTATION_ROTATE_270) {
@@ -150,7 +155,8 @@ public final class DngCreator implements AutoCloseable {
      * @throws java.lang.IllegalArgumentException if the given thumbnail image has a dimension
      *      larger than {@link #MAX_THUMBNAIL_DIMENSION}.
      */
-    public DngCreator setThumbnail(Bitmap pixels) {
+    @NonNull
+    public DngCreator setThumbnail(@NonNull Bitmap pixels) {
         if (pixels == null) {
             throw new IllegalArgumentException("Null argument to setThumbnail");
         }
@@ -185,7 +191,8 @@ public final class DngCreator implements AutoCloseable {
      * @throws java.lang.IllegalArgumentException if the given thumbnail image has a dimension
      *      larger than {@link #MAX_THUMBNAIL_DIMENSION}.
      */
-    public DngCreator setThumbnail(Image pixels) {
+    @NonNull
+    public DngCreator setThumbnail(@NonNull Image pixels) {
         if (pixels == null) {
             throw new IllegalArgumentException("Null argument to setThumbnail");
         }
@@ -226,7 +233,8 @@ public final class DngCreator implements AutoCloseable {
      * @throws java.lang.IllegalArgumentException if the given location object doesn't
      *          contain enough information to set location metadata.
      */
-    public DngCreator setLocation(Location location) {
+    @NonNull
+    public DngCreator setLocation(@NonNull Location location) {
         if (location == null) {
             throw new IllegalArgumentException("Null location passed to setLocation");
         }
@@ -258,7 +266,8 @@ public final class DngCreator implements AutoCloseable {
      * @param description the user description string.
      * @return this {@link #DngCreator} object.
      */
-    public DngCreator setDescription(String description) {
+    @NonNull
+    public DngCreator setDescription(@NonNull String description) {
         if (description == null) {
             throw new IllegalArgumentException("Null description passed to setDescription.");
         }
@@ -293,8 +302,8 @@ public final class DngCreator implements AutoCloseable {
      *          set to write a well-formatted DNG file.
      * @throws java.lang.IllegalArgumentException if the size passed in does not match the
      */
-    public void writeInputStream(OutputStream dngOutput, Size size, InputStream pixels, long offset)
+    public void writeInputStream(@NonNull OutputStream dngOutput, @NonNull Size size,
-            throws IOException {
+            @NonNull InputStream pixels, @IntRange(from=0) long offset) throws IOException {
         if (dngOutput == null) {
             throw new IllegalArgumentException("Null dngOutput passed to writeInputStream");
         } else if (size == null) {
@@ -345,7 +354,8 @@ public final class DngCreator implements AutoCloseable {
      * @throws java.lang.IllegalStateException if not enough metadata information has been
      *          set to write a well-formatted DNG file.
      */
-    public void writeByteBuffer(OutputStream dngOutput, Size size, ByteBuffer pixels, long offset)
+    public void writeByteBuffer(@NonNull OutputStream dngOutput, @NonNull Size size,
+            @NonNull ByteBuffer pixels, @IntRange(from=0) long offset)
             throws IOException {
         if (dngOutput == null) {
             throw new IllegalArgumentException("Null dngOutput passed to writeByteBuffer");
@@ -381,7 +391,8 @@ public final class DngCreator implements AutoCloseable {
      * @throws java.lang.IllegalStateException if not enough metadata information has been
      *          set to write a well-formatted DNG file.
      */
-    public void writeImage(OutputStream dngOutput, Image pixels) throws IOException {
+    public void writeImage(@NonNull OutputStream dngOutput, @NonNull Image pixels)
+            throws IOException {
         if (dngOutput == null) {
             throw new IllegalArgumentException("Null dngOutput to writeImage");
         } else if (pixels == null) {

core/java/android/hardware/camera2/TotalCaptureResult.java

@@ -16,6 +16,7 @@
 
 package android.hardware.camera2;
 
+import android.annotation.NonNull;
 import android.hardware.camera2.impl.CameraMetadataNative;
 import android.hardware.camera2.impl.CaptureResultExtras;
 
@@ -96,6 +97,7 @@ public final class TotalCaptureResult extends CaptureResult {
      *
      * @return unmodifiable list of partial results
      */
+    @NonNull
     public List<CaptureResult> getPartialResults() {
         return Collections.unmodifiableList(mPartialResults);
     }

core/java/android/hardware/camera2/impl/CameraDeviceImpl.java

@@ -607,6 +607,8 @@ public class CameraDeviceImpl extends CameraDevice {
     }
 
     public void prepare(Surface surface) throws CameraAccessException {
+        if (surface == null) throw new IllegalArgumentException("Surface is null");
+
         synchronized(mInterfaceLock) {
             int streamId = -1;
             for (int i = 0; i < mConfiguredOutputs.size(); i++) {