From fbad62d057e79edb3c6d011e6ad2422db51247a3 Mon Sep 17 00:00:00 2001 From: tobrun Date: Wed, 16 May 2018 17:37:04 +0200 Subject: [PATCH] [android] - add nullability annotations to public api for kotlin language integration --- .../com/mapbox/mapboxsdk/maps/MapView.java | 24 ++-- .../com/mapbox/mapboxsdk/maps/MapboxMap.java | 103 +++++++++++------- .../com/mapbox/mapboxsdk/maps/Projection.java | 13 ++- .../com/mapbox/mapboxsdk/maps/UiSettings.java | 6 +- 4 files changed, 83 insertions(+), 63 deletions(-) diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java index 4ecd7c92468..687d42cac36 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java @@ -23,7 +23,6 @@ import android.widget.FrameLayout; import android.widget.ImageView; import android.widget.ZoomButtonsController; - import com.mapbox.android.gestures.AndroidGesturesManager; import com.mapbox.android.telemetry.AppUserTurnstile; import com.mapbox.android.telemetry.Event; @@ -43,6 +42,8 @@ import com.mapbox.mapboxsdk.storage.FileSource; import com.mapbox.mapboxsdk.utils.BitmapUtils; +import javax.microedition.khronos.egl.EGLConfig; +import javax.microedition.khronos.opengles.GL10; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.ref.WeakReference; @@ -51,9 +52,6 @@ import java.util.List; import java.util.concurrent.CopyOnWriteArrayList; -import javax.microedition.khronos.egl.EGLConfig; -import javax.microedition.khronos.opengles.GL10; - import static com.mapbox.mapboxsdk.maps.widgets.CompassView.TIME_MAP_NORTH_ANIMATION; import static com.mapbox.mapboxsdk.maps.widgets.CompassView.TIME_WAIT_IDLE; @@ -598,10 +596,8 @@ public Bitmap getViewContent() { * @param listener The callback that's invoked on every frame rendered to the map view. * @see MapView#removeOnMapChangedListener(OnMapChangedListener) */ - public void addOnMapChangedListener(@Nullable OnMapChangedListener listener) { - if (listener != null) { - onMapChangedListeners.add(listener); - } + public void addOnMapChangedListener(@NonNull OnMapChangedListener listener) { + onMapChangedListeners.add(listener); } /** @@ -610,8 +606,8 @@ public void addOnMapChangedListener(@Nullable OnMapChangedListener listener) { * @param listener The previously added callback to remove. * @see MapView#addOnMapChangedListener(OnMapChangedListener) */ - public void removeOnMapChangedListener(@Nullable OnMapChangedListener listener) { - if (listener != null && onMapChangedListeners.contains(listener)) { + public void removeOnMapChangedListener(@NonNull OnMapChangedListener listener) { + if (onMapChangedListeners.contains(listener)) { onMapChangedListeners.remove(listener); } } @@ -622,13 +618,11 @@ public void removeOnMapChangedListener(@Nullable OnMapChangedListener listener) * @param callback The callback object that will be triggered when the map is ready to be used. */ @UiThread - public void getMapAsync(final OnMapReadyCallback callback) { - if (!mapCallback.isInitialLoad() && callback != null) { + public void getMapAsync(final @NonNull OnMapReadyCallback callback) { + if (!mapCallback.isInitialLoad()) { callback.onMapReady(mapboxMap); } else { - if (callback != null) { - mapCallback.addOnMapReadyCallback(callback); - } + mapCallback.addOnMapReadyCallback(callback); } } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java index cfa71436712..aed918cb791 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java @@ -120,7 +120,7 @@ void onStop() { * * @param outState the bundle to save the state to. */ - void onSaveInstanceState(Bundle outState) { + void onSaveInstanceState(@NonNull Bundle outState) { outState.putParcelable(MapboxConstants.STATE_CAMERA_POSITION, transform.getCameraPosition()); outState.putBoolean(MapboxConstants.STATE_DEBUG_ACTIVE, nativeMapView.getDebug()); outState.putString(MapboxConstants.STATE_STYLE_URL, nativeMapView.getStyleUrl()); @@ -132,7 +132,7 @@ void onSaveInstanceState(Bundle outState) { * * @param savedInstanceState the bundle containing the saved state */ - void onRestoreInstanceState(Bundle savedInstanceState) { + void onRestoreInstanceState(@NonNull Bundle savedInstanceState) { final CameraPosition cameraPosition = savedInstanceState.getParcelable(MapboxConstants.STATE_CAMERA_POSITION); uiSettings.onRestoreInstanceState(savedInstanceState); @@ -266,6 +266,7 @@ public boolean getPrefetchesTiles() { * * @return all the layers in the current style */ + @NonNull public List getLayers() { return nativeMapView.getLayers(); } @@ -377,6 +378,7 @@ public Layer removeLayerAt(@IntRange(from = 0) int index) { * * @return all the sources in the current style */ + @NonNull public List getSources() { return nativeMapView.getSources(); } @@ -463,10 +465,11 @@ public void addImages(@NonNull HashMap images) { * * @param name the name of the image to remove */ - public void removeImage(String name) { + public void removeImage(@NonNull String name) { nativeMapView.removeImage(name); } + @Nullable public Bitmap getImage(@NonNull String name) { return nativeMapView.getImage(name); } @@ -537,6 +540,7 @@ public double getMaxZoomLevel() { * * @return the UiSettings associated with this map */ + @NonNull public UiSettings getUiSettings() { return uiSettings; } @@ -551,6 +555,7 @@ public UiSettings getUiSettings() { * * @return the Projection associated with this map */ + @NonNull public Projection getProjection() { return projection; } @@ -564,7 +569,7 @@ public Projection getProjection() { * * @return the global light source */ - @Nullable + @NonNull public Light getLight() { return nativeMapView.getLight(); } @@ -590,6 +595,7 @@ public void cancelTransitions() { * * @return The current position of the Camera. */ + @NonNull public final CameraPosition getCameraPosition() { return transform.getCameraPosition(); } @@ -612,7 +618,7 @@ public void setCameraPosition(@NonNull CameraPosition cameraPosition) { * * @param update The change that should be applied to the camera. */ - public final void moveCamera(CameraUpdate update) { + public final void moveCamera(@NonNull CameraUpdate update) { moveCamera(update, null); } @@ -624,7 +630,8 @@ public final void moveCamera(CameraUpdate update) { * @param update The change that should be applied to the camera * @param callback the callback to be invoked when an animation finishes or is canceled */ - public final void moveCamera(final CameraUpdate update, final MapboxMap.CancelableCallback callback) { + public final void moveCamera(@NonNull final CameraUpdate update, + @Nullable final MapboxMap.CancelableCallback callback) { transform.moveCamera(MapboxMap.this, update, callback); } @@ -650,7 +657,7 @@ public final void easeCamera(CameraUpdate update) { * positive, otherwise an IllegalArgumentException will be thrown. * @see com.mapbox.mapboxsdk.camera.CameraUpdateFactory for a set of updates. */ - public final void easeCamera(CameraUpdate update, int durationMs) { + public final void easeCamera(@NonNull CameraUpdate update, int durationMs) { easeCamera(update, durationMs, null); } @@ -673,7 +680,8 @@ public final void easeCamera(CameraUpdate update, int durationMs) { * Do not update or ease the camera from within onCancel(). * @see com.mapbox.mapboxsdk.camera.CameraUpdateFactory for a set of updates. */ - public final void easeCamera(CameraUpdate update, int durationMs, final MapboxMap.CancelableCallback callback) { + public final void easeCamera(@NonNull CameraUpdate update, int durationMs, + @Nullable final MapboxMap.CancelableCallback callback) { easeCamera(update, durationMs, true, callback); } @@ -691,7 +699,7 @@ public final void easeCamera(CameraUpdate update, int durationMs, final MapboxMa * positive, otherwise an IllegalArgumentException will be thrown. * @param easingInterpolator True for easing interpolator, false for linear. */ - public final void easeCamera(CameraUpdate update, int durationMs, boolean easingInterpolator) { + public final void easeCamera(@NonNull CameraUpdate update, int durationMs, boolean easingInterpolator) { easeCamera(update, durationMs, easingInterpolator, null); } @@ -711,8 +719,10 @@ public final void easeCamera(CameraUpdate update, int durationMs, boolean easing * by a later camera movement or a user gesture, onCancel() will be called. * Do not update or ease the camera from within onCancel(). */ - public final void easeCamera(final CameraUpdate update, final int durationMs, final boolean easingInterpolator, - final MapboxMap.CancelableCallback callback) { + public final void easeCamera(@NonNull final CameraUpdate update, + final int durationMs, + final boolean easingInterpolator, + @Nullable final MapboxMap.CancelableCallback callback) { easeCamera(update, durationMs, easingInterpolator, callback, false); } @@ -733,8 +743,9 @@ public final void easeCamera(final CameraUpdate update, final int durationMs, fi * Do not update or ease the camera from within onCancel(). * @param isDismissable true will allow animated camera changes dismiss a tracking mode. */ - public final void easeCamera(final CameraUpdate update, final int durationMs, final boolean easingInterpolator, - final MapboxMap.CancelableCallback callback, final boolean isDismissable) { + public final void easeCamera(@NonNull final CameraUpdate update, final int durationMs, + final boolean easingInterpolator, @Nullable final MapboxMap.CancelableCallback callback, + final boolean isDismissable) { if (durationMs <= 0) { throw new IllegalArgumentException("Null duration passed into easeCamera"); @@ -751,7 +762,7 @@ public final void easeCamera(final CameraUpdate update, final int durationMs, fi * @param update The change that should be applied to the camera. * @see com.mapbox.mapboxsdk.camera.CameraUpdateFactory for a set of updates. */ - public final void animateCamera(CameraUpdate update) { + public final void animateCamera(@NonNull CameraUpdate update) { animateCamera(update, MapboxConstants.ANIMATION_DURATION, null); } @@ -767,7 +778,7 @@ public final void animateCamera(CameraUpdate update) { * called. Do not update or animate the camera from within onCancel(). * @see com.mapbox.mapboxsdk.camera.CameraUpdateFactory for a set of updates. */ - public final void animateCamera(CameraUpdate update, MapboxMap.CancelableCallback callback) { + public final void animateCamera(@NonNull CameraUpdate update, @Nullable MapboxMap.CancelableCallback callback) { animateCamera(update, MapboxConstants.ANIMATION_DURATION, callback); } @@ -782,7 +793,7 @@ public final void animateCamera(CameraUpdate update, MapboxMap.CancelableCallbac * positive, otherwise an IllegalArgumentException will be thrown. * @see com.mapbox.mapboxsdk.camera.CameraUpdateFactory for a set of updates. */ - public final void animateCamera(CameraUpdate update, int durationMs) { + public final void animateCamera(@NonNull CameraUpdate update, int durationMs) { animateCamera(update, durationMs, null); } @@ -804,8 +815,8 @@ public final void animateCamera(CameraUpdate update, int durationMs) { * isn't required, leave it as null. * @see com.mapbox.mapboxsdk.camera.CameraUpdateFactory for a set of updates. */ - public final void animateCamera(final CameraUpdate update, final int durationMs, - final MapboxMap.CancelableCallback callback) { + public final void animateCamera(@NonNull final CameraUpdate update, final int durationMs, + @Nullable final MapboxMap.CancelableCallback callback) { if (durationMs <= 0) { throw new IllegalArgumentException("Null duration passed into animageCamera"); } @@ -1069,6 +1080,7 @@ public void setStyleJson(@NonNull String styleJson) { * * @return The json of the map style */ + @NonNull public String getStyleJson() { return nativeMapView.getStyleJson(); } @@ -1232,7 +1244,7 @@ public List addPolylines(@NonNull List polylineOption * * @param polyline An updated polyline object. */ - public void updatePolyline(Polyline polyline) { + public void updatePolyline(@NonNull Polyline polyline) { annotationManager.updatePolyline(polyline); } @@ -1263,7 +1275,7 @@ public List addPolygons(@NonNull List polygonOptionsLis * * @param polygon An updated polygon object */ - public void updatePolygon(Polygon polygon) { + public void updatePolygon(@NonNull Polygon polygon) { annotationManager.updatePolygon(polygon); } @@ -1468,6 +1480,7 @@ public void deselectMarker(@NonNull Marker marker) { * * @return The currently selected marker. */ + @NonNull public List getSelectedMarkers() { return annotationManager.getSelectedMarkers(); } @@ -1477,6 +1490,7 @@ public List getSelectedMarkers() { * * @return the associated MarkerViewManager */ + @NonNull public MarkerViewManager getMarkerViewManager() { return annotationManager.getMarkerViewManager(); } @@ -1550,6 +1564,7 @@ public void setLatLngBoundsForCameraTarget(@Nullable LatLngBounds latLngBounds) * @param padding the padding to apply to the bounds * @return the camera position that fits the bounds and padding */ + @NonNull public CameraPosition getCameraForLatLngBounds(@NonNull LatLngBounds latLngBounds, int[] padding) { // get padded camera position from LatLngBounds return nativeMapView.getCameraForLatLngBounds(latLngBounds, padding); @@ -1563,6 +1578,7 @@ public CameraPosition getCameraForLatLngBounds(@NonNull LatLngBounds latLngBound * @param padding the padding to apply to the bounds * @return the camera position that fits the bounds and padding */ + @NonNull public CameraPosition getCameraForGeometry(Geometry geometry, double bearing, int[] padding) { // get padded camera position from Geometry return nativeMapView.getCameraForGeometry(geometry, bearing, padding); @@ -1591,11 +1607,7 @@ public CameraPosition getCameraForGeometry(Geometry geometry, double bearing, in * @param bottom The bottom margin in pixels. */ public void setPadding(int left, int top, int right, int bottom) { - setPadding(new int[] {left, top, right, bottom}); - } - - private void setPadding(int[] padding) { - projection.setContentPadding(padding); + projection.setContentPadding(new int[] {left, top, right, bottom}); uiSettings.invalidate(); } @@ -1604,6 +1616,7 @@ private void setPadding(int[] padding) { * * @return An array with length 4 in the LTRB order. */ + @NonNull public int[] getPadding() { return projection.getContentPadding(); } @@ -1755,6 +1768,7 @@ public void setOnFpsChangedListener(@Nullable OnFpsChangedListener listener) { } // used by MapView + @Nullable OnFpsChangedListener getOnFpsChangedListener() { return onFpsChangedListener; } @@ -1902,7 +1916,7 @@ public void removeOnShoveListener(@NonNull OnShoveListener listener) { * will be added to the passed gestures manager. * @see mapbox-gestures-android library */ - public void setGesturesManager(AndroidGesturesManager androidGesturesManager, boolean attachDefaultListeners, + public void setGesturesManager(@NonNull AndroidGesturesManager androidGesturesManager, boolean attachDefaultListeners, boolean setDefaultMutuallyExclusives) { onGesturesManagerInteractionListener.setGesturesManager( androidGesturesManager, attachDefaultListeners, setDefaultMutuallyExclusives); @@ -1914,6 +1928,7 @@ public void setGesturesManager(AndroidGesturesManager androidGesturesManager, bo * * @return Current gestures manager. */ + @NonNull public AndroidGesturesManager getGesturesManager() { return onGesturesManagerInteractionListener.getGesturesManager(); } @@ -2000,6 +2015,7 @@ public void setOnInfoWindowClickListener(@Nullable OnInfoWindowClickListener lis * * @return Current active InfoWindow Click Listener */ + @Nullable public OnInfoWindowClickListener getOnInfoWindowClickListener() { return annotationManager.getInfoWindowManager().getOnInfoWindowClickListener(); } @@ -2020,6 +2036,7 @@ public void setOnInfoWindowLongClickListener(@Nullable OnInfoWindowLongClickList * * @return Current active InfoWindow long Click Listener */ + @Nullable public OnInfoWindowLongClickListener getOnInfoWindowLongClickListener() { return annotationManager.getInfoWindowManager().getOnInfoWindowLongClickListener(); } @@ -2038,6 +2055,7 @@ public void setOnInfoWindowCloseListener(@Nullable OnInfoWindowCloseListener lis * * @return Current active InfoWindow Close Listener */ + @Nullable public OnInfoWindowCloseListener getOnInfoWindowCloseListener() { return annotationManager.getInfoWindowManager().getOnInfoWindowCloseListener(); } @@ -2147,11 +2165,11 @@ public interface OnScrollListener { * @see MapboxMap#addOnMoveListener(OnMoveListener) */ public interface OnMoveListener { - void onMoveBegin(MoveGestureDetector detector); + void onMoveBegin(@NonNull MoveGestureDetector detector); - void onMove(MoveGestureDetector detector); + void onMove(@NonNull MoveGestureDetector detector); - void onMoveEnd(MoveGestureDetector detector); + void onMoveEnd(@NonNull MoveGestureDetector detector); } /** @@ -2160,11 +2178,11 @@ public interface OnMoveListener { * @see MapboxMap#addOnRotateListener(OnRotateListener) */ public interface OnRotateListener { - void onRotateBegin(RotateGestureDetector detector); + void onRotateBegin(@NonNull RotateGestureDetector detector); - void onRotate(RotateGestureDetector detector); + void onRotate(@NonNull RotateGestureDetector detector); - void onRotateEnd(RotateGestureDetector detector); + void onRotateEnd(@NonNull RotateGestureDetector detector); } /** @@ -2173,11 +2191,11 @@ public interface OnRotateListener { * @see MapboxMap#addOnScaleListener(OnScaleListener) */ public interface OnScaleListener { - void onScaleBegin(StandardScaleGestureDetector detector); + void onScaleBegin(@NonNull StandardScaleGestureDetector detector); - void onScale(StandardScaleGestureDetector detector); + void onScale(@NonNull StandardScaleGestureDetector detector); - void onScaleEnd(StandardScaleGestureDetector detector); + void onScaleEnd(@NonNull StandardScaleGestureDetector detector); } /** @@ -2186,11 +2204,11 @@ public interface OnScaleListener { * @see MapboxMap#addOnShoveListener(OnShoveListener) */ public interface OnShoveListener { - void onShoveBegin(ShoveGestureDetector detector); + void onShoveBegin(@NonNull ShoveGestureDetector detector); - void onShove(ShoveGestureDetector detector); + void onShove(@NonNull ShoveGestureDetector detector); - void onShoveEnd(ShoveGestureDetector detector); + void onShoveEnd(@NonNull ShoveGestureDetector detector); } /** @@ -2442,7 +2460,7 @@ public interface OnInfoWindowLongClickListener { * * @param marker The marker were the info window is attached to */ - void onInfoWindowLongClick(Marker marker); + void onInfoWindowLongClick(@NonNull Marker marker); } /** @@ -2457,7 +2475,7 @@ public interface OnInfoWindowCloseListener { * * @param marker The marker of the info window that was closed. */ - void onInfoWindowClose(Marker marker); + void onInfoWindowClose(@NonNull Marker marker); } /** @@ -2637,7 +2655,7 @@ public interface SnapshotReadyCallback { * * @param snapshot the snapshot bitmap */ - void onSnapshotReady(Bitmap snapshot); + void onSnapshotReady(@NonNull Bitmap snapshot); } /** @@ -2649,12 +2667,13 @@ public interface OnStyleLoadedListener { * * @param style the style that has been loaded */ - void onStyleLoaded(String style); + void onStyleLoaded(@NonNull String style); } // // Used for instrumentation testing // + @NonNull Transform getTransform() { return transform; } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/Projection.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/Projection.java index f35355533d1..d5166c17b0e 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/Projection.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/Projection.java @@ -43,14 +43,16 @@ public void invalidateContentPadding() { /** * Returns the spherical Mercator projected meters for a LatLng. */ - public ProjectedMeters getProjectedMetersForLatLng(LatLng latLng) { + @NonNull + public ProjectedMeters getProjectedMetersForLatLng(@NonNull LatLng latLng) { return nativeMapView.projectedMetersForLatLng(latLng); } /** * Returns the LatLng for a spherical Mercator projected meters. */ - public LatLng getLatLngForProjectedMeters(ProjectedMeters projectedMeters) { + @NonNull + public LatLng getLatLngForProjectedMeters(@NonNull ProjectedMeters projectedMeters) { return nativeMapView.latLngForProjectedMeters(projectedMeters); } @@ -77,7 +79,8 @@ public double getMetersPerPixelAtLatitude(@FloatRange(from = -90, to = 90) doubl * @return The LatLng corresponding to the point on the screen, or null if the ray through * the given screen point does not intersect the ground plane. */ - public LatLng fromScreenLocation(PointF point) { + @NonNull + public LatLng fromScreenLocation(@NonNull PointF point) { return nativeMapView.latLngForPixel(point); } @@ -87,6 +90,7 @@ public LatLng fromScreenLocation(PointF point) { * * @return The projection of the viewing frustum in its current state. */ + @NonNull public VisibleRegion getVisibleRegion() { float left = 0; float right = nativeMapView.getWidth(); @@ -151,7 +155,8 @@ public VisibleRegion getVisibleRegion() { * @param location A LatLng on the map to convert to a screen location. * @return A Point representing the screen location in screen pixels. */ - public PointF toScreenLocation(LatLng location) { + @NonNull + public PointF toScreenLocation(@NonNull LatLng location) { return nativeMapView.pixelForLatLng(location); } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java index c1daebbe520..100787fbf0b 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java @@ -332,7 +332,7 @@ public void setCompassFadeFacingNorth(boolean compassFadeFacingNorth) { * * @param compass the drawable to show as image compass */ - public void setCompassImage(Drawable compass) { + public void setCompassImage(@NonNull Drawable compass) { compassView.setCompassImage(compass); } @@ -409,6 +409,7 @@ public int getCompassMarginBottom() { * * @return the drawable used as compass image */ + @NonNull public Drawable getCompassImage() { return compassView.getCompassImage(); } @@ -544,7 +545,7 @@ public boolean isAttributionEnabled() { * * @param attributionDialogManager the manager class used for showing attribution */ - public void setAttributionDialogManager(AttributionDialogManager attributionDialogManager) { + public void setAttributionDialogManager(@NonNull AttributionDialogManager attributionDialogManager) { this.attributionDialogManager = attributionDialogManager; } @@ -553,6 +554,7 @@ public void setAttributionDialogManager(AttributionDialogManager attributionDial * * @return the active manager class used for showing attribution */ + @NonNull public AttributionDialogManager getAttributionDialogManager() { return attributionDialogManager; }