1 /*
2  * Copyright (C) 2018 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.location;
18 
19 import android.annotation.FloatRange;
20 import android.annotation.NonNull;
21 import android.annotation.SystemApi;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 import java.util.Objects;
26 
27 /**
28  * Holds the characteristics of the reflecting plane that a satellite signal has bounced from.
29  *
30  * <p>Starting with Android T, this class supports {@link #equals} and {@link #hashCode}, which
31  * are not supported before that.
32  *
33  * @hide
34  */
35 @SystemApi
36 public final class GnssReflectingPlane implements Parcelable {
37 
38     /** Represents latitude in degrees of the reflecting plane */
39     @FloatRange(from = -90.0f, to = 90.0f)
40     private final double mLatitudeDegrees;
41     /** Represents longitude in degrees of the reflecting plane. */
42     @FloatRange(from = -180.0f, to = 180.0f)
43     private final double mLongitudeDegrees;
44     /**
45      * Represents altitude in meters above the WGS 84 reference ellipsoid of the reflection point in
46      * the plane
47      */
48     @FloatRange(from = -1000.0f, to = 10000.0f)
49     private final double mAltitudeMeters;
50 
51     /** Represents azimuth clockwise from north of the reflecting plane in degrees. */
52     @FloatRange(from = 0.0f, to = 360.0f)
53     private final double mAzimuthDegrees;
54 
GnssReflectingPlane(Builder builder)55     private GnssReflectingPlane(Builder builder) {
56         mLatitudeDegrees = builder.mLatitudeDegrees;
57         mLongitudeDegrees = builder.mLongitudeDegrees;
58         mAltitudeMeters = builder.mAltitudeMeters;
59         mAzimuthDegrees = builder.mAzimuthDegrees;
60     }
61 
62     /** Gets the latitude in degrees of the reflecting plane. */
63     @FloatRange(from = -90.0f, to = 90.0f)
getLatitudeDegrees()64     public double getLatitudeDegrees() {
65         return mLatitudeDegrees;
66     }
67 
68     /** Gets the longitude in degrees of the reflecting plane. */
69     @FloatRange(from = -180.0f, to = 180.0f)
getLongitudeDegrees()70     public double getLongitudeDegrees() {
71         return mLongitudeDegrees;
72     }
73 
74     /**
75      * Gets the altitude in meters above the WGS 84 reference ellipsoid of the reflecting point
76      * within the plane
77      */
78     @FloatRange(from = -1000.0f, to = 10000.0f)
getAltitudeMeters()79     public double getAltitudeMeters() {
80         return mAltitudeMeters;
81     }
82 
83     /** Gets the azimuth clockwise from north of the reflecting plane in degrees. */
84     @FloatRange(from = 0.0f, to = 360.0f)
getAzimuthDegrees()85     public double getAzimuthDegrees() {
86         return mAzimuthDegrees;
87     }
88 
89     @Override
describeContents()90     public int describeContents() {
91         return 0;
92     }
93 
94     public static final Creator<GnssReflectingPlane> CREATOR =
95             new Creator<GnssReflectingPlane>() {
96                 @Override
97                 @NonNull
98                 public GnssReflectingPlane createFromParcel(@NonNull Parcel parcel) {
99                     GnssReflectingPlane reflectingPlane =
100                             new Builder()
101                                     .setLatitudeDegrees(parcel.readDouble())
102                                     .setLongitudeDegrees(parcel.readDouble())
103                                     .setAltitudeMeters(parcel.readDouble())
104                                     .setAzimuthDegrees(parcel.readDouble())
105                                     .build();
106                     return reflectingPlane;
107                 }
108 
109                 @Override
110                 public GnssReflectingPlane[] newArray(int i) {
111                     return new GnssReflectingPlane[i];
112                 }
113             };
114 
115     @Override
writeToParcel(@onNull Parcel parcel, int flags)116     public void writeToParcel(@NonNull Parcel parcel, int flags) {
117         parcel.writeDouble(mLatitudeDegrees);
118         parcel.writeDouble(mLongitudeDegrees);
119         parcel.writeDouble(mAltitudeMeters);
120         parcel.writeDouble(mAzimuthDegrees);
121     }
122 
123     @NonNull
124     @Override
toString()125     public String toString() {
126         StringBuilder builder = new StringBuilder("ReflectingPlane[");
127         builder.append(" LatitudeDegrees=").append(mLatitudeDegrees);
128         builder.append(" LongitudeDegrees=").append(mLongitudeDegrees);
129         builder.append(" AltitudeMeters=").append(mAltitudeMeters);
130         builder.append(" AzimuthDegrees=").append(mAzimuthDegrees);
131         builder.append(']');
132         return builder.toString();
133     }
134 
135     @Override
equals(Object obj)136     public boolean equals(Object obj) {
137         if (obj instanceof GnssReflectingPlane) {
138             GnssReflectingPlane that = (GnssReflectingPlane) obj;
139             return Double.compare(this.mLatitudeDegrees, that.mLatitudeDegrees) == 0
140                     && Double.compare(this.mLongitudeDegrees, that.mLongitudeDegrees) == 0
141                     && Double.compare(this.mAltitudeMeters, that.mAltitudeMeters) == 0
142                     && Double.compare(this.mAzimuthDegrees, that.mAzimuthDegrees) == 0;
143         }
144         return false;
145     }
146 
147     @Override
hashCode()148     public int hashCode() {
149         return Objects.hash(mLatitudeDegrees, mLatitudeDegrees, mAltitudeMeters, mAzimuthDegrees);
150     }
151 
152     /** Builder for {@link GnssReflectingPlane} */
153     public static final class Builder {
154         /** For documentation, see corresponding fields in {@link GnssReflectingPlane}. */
155         private double mLatitudeDegrees;
156         private double mLongitudeDegrees;
157         private double mAltitudeMeters;
158         private double mAzimuthDegrees;
159 
160         /** Sets the latitude in degrees of the reflecting plane. */
setLatitudeDegrees( @loatRangefrom = -90.0f, to = 90.0f) double latitudeDegrees)161         @NonNull public Builder setLatitudeDegrees(
162                 @FloatRange(from = -90.0f, to = 90.0f) double latitudeDegrees) {
163             mLatitudeDegrees = latitudeDegrees;
164             return this;
165         }
166 
167         /** Sets the longitude in degrees of the reflecting plane. */
setLongitudeDegrees( @loatRangefrom = -180.0f, to = 180.0f) double longitudeDegrees)168         @NonNull public Builder setLongitudeDegrees(
169                 @FloatRange(from = -180.0f, to = 180.0f) double longitudeDegrees) {
170             mLongitudeDegrees = longitudeDegrees;
171             return this;
172         }
173 
174         /**
175          * Sets the altitude in meters above the WGS 84 reference ellipsoid of the reflecting point
176          * within the plane
177          */
setAltitudeMeters( @loatRangefrom = -1000.0f, to = 10000.0f) double altitudeMeters)178         @NonNull public Builder setAltitudeMeters(
179                 @FloatRange(from = -1000.0f, to = 10000.0f) double altitudeMeters) {
180             mAltitudeMeters = altitudeMeters;
181             return this;
182         }
183 
184         /** Sets the azimuth clockwise from north of the reflecting plane in degrees. */
setAzimuthDegrees( @loatRangefrom = 0.0f, to = 360.0f) double azimuthDegrees)185         @NonNull public Builder setAzimuthDegrees(
186                 @FloatRange(from = 0.0f, to = 360.0f) double azimuthDegrees) {
187             mAzimuthDegrees = azimuthDegrees;
188             return this;
189         }
190 
191         /** Builds a {@link GnssReflectingPlane} object as specified by this builder. */
build()192         @NonNull public GnssReflectingPlane build() {
193             return new GnssReflectingPlane(this);
194         }
195     }
196 }
197