From 06d5c89c437cd9a25078c10c5198bf67c789902e Mon Sep 17 00:00:00 2001 From: Luis Vidal Date: Wed, 6 Apr 2016 18:07:31 -0700 Subject: [PATCH] Add state member to WeatherLocation class Some weather service providers might require an additional state (territory) field to better identify a location, so a new field has been added to WeatherLocation class to hold this data. This patch also adds javadoc to public methods TICKET: CYNGNOS-2384 Change-Id: I927f58d436f044df3c8af496b0f27e017f5e73e3 --- api/cm_current.txt | 2 + .../cyanogenmod/weather/WeatherLocation.java | 88 +++++++++++++++++-- system-api/cm_system-current.txt | 2 + 3 files changed, 84 insertions(+), 8 deletions(-) diff --git a/api/cm_current.txt b/api/cm_current.txt index a00cf44..4c39eec 100644 --- a/api/cm_current.txt +++ b/api/cm_current.txt @@ -1391,6 +1391,7 @@ package cyanogenmod.weather { method public java.lang.String getCountry(); method public java.lang.String getCountryId(); method public java.lang.String getPostalCode(); + method public java.lang.String getState(); method public void writeToParcel(android.os.Parcel, int); field public static final android.os.Parcelable.Creator CREATOR; } @@ -1400,6 +1401,7 @@ package cyanogenmod.weather { method public cyanogenmod.weather.WeatherLocation build(); method public cyanogenmod.weather.WeatherLocation.Builder setCountry(java.lang.String, java.lang.String); method public cyanogenmod.weather.WeatherLocation.Builder setPostalCode(java.lang.String); + method public cyanogenmod.weather.WeatherLocation.Builder setState(java.lang.String); } } diff --git a/sdk/src/java/cyanogenmod/weather/WeatherLocation.java b/sdk/src/java/cyanogenmod/weather/WeatherLocation.java index 3afcd8e..6cc4741 100644 --- a/sdk/src/java/cyanogenmod/weather/WeatherLocation.java +++ b/sdk/src/java/cyanogenmod/weather/WeatherLocation.java @@ -19,6 +19,7 @@ package cyanogenmod.weather; import android.os.Parcel; import android.os.Parcelable; +import android.text.TextUtils; import cyanogenmod.os.Build; import cyanogenmod.os.Concierge; import cyanogenmod.os.Concierge.ParcelInfo; @@ -32,6 +33,7 @@ import cyanogenmod.os.Concierge.ParcelInfo; public final class WeatherLocation implements Parcelable{ private String mCityId; private String mCity; + private String mState; private String mPostal; private String mCountryId; private String mCountry; @@ -39,33 +41,78 @@ public final class WeatherLocation implements Parcelable{ private WeatherLocation() {} + /** + * Builder class for {@link WeatherLocation} + */ public static class Builder { - String mCityId; - String mCity; - String mPostal; - String mCountryId; - String mCountry; + String mCityId = ""; + String mCity = ""; + String mState = ""; + String mPostal = ""; + String mCountryId = ""; + String mCountry = ""; + /** + * @param cityId An identifier for the city (for example WOEID - Where On Earth IDentifier) + * @param cityName The name of the city + */ public Builder(String cityId, String cityName) { + if (cityId == null && cityName == null) { + throw new IllegalArgumentException("Illegal to set city id AND city to null"); + } this.mCityId = cityId; this.mCity = cityName; } - public Builder setCountry(String countyId, String country) { - this.mCountryId = countyId; + /** + * @param countryId An identifier for the country (for example ISO alpha-2, ISO alpha-3, + * ISO 3166-1 numeric-3, etc) + * @param country The country name + * @return The {@link Builder} instance + */ + public Builder setCountry(String countryId, String country) { + if (countryId == null && country == null) { + throw new IllegalArgumentException("Illegal to set country id AND country to null"); + } + this.mCountryId = countryId; this.mCountry = country; return this; } + /** + * @param postalCode The postal/ZIP code + * @return The {@link Builder} instance + */ public Builder setPostalCode(String postalCode) { + if (postalCode == null) { + throw new IllegalArgumentException("Postal code/ZIP can't be null"); + } this.mPostal = postalCode; return this; } + /** + * @param state The state or territory where the city is located + * @return The {@link Builder} instance + */ + public Builder setState(String state) { + if (state == null) { + throw new IllegalArgumentException("State can't be null"); + } + this.mState = state; + return this; + } + + /** + * Combine all of the options that have been set and return a new {@link WeatherLocation} + * object + * @return {@link WeatherLocation} + */ public WeatherLocation build() { WeatherLocation weatherLocation = new WeatherLocation(); weatherLocation.mCityId = this.mCityId; weatherLocation.mCity = this.mCity; + weatherLocation.mState = this.mState; weatherLocation.mPostal = this.mPostal; weatherLocation.mCountryId = this.mCountryId; weatherLocation.mCountry = this.mCountry; @@ -74,22 +121,44 @@ public final class WeatherLocation implements Parcelable{ } } + /** + * @return The city ID + */ public String getCityId() { return mCityId; } + /** + * @return The city name + */ public String getCity() { return mCity; } + /** + * @return The state name + */ + public String getState() { + return mState; + } + + /** + * @return The postal/ZIP code + */ public String getPostalCode() { return mPostal; } + /** + * @return The country ID + */ public String getCountryId() { return mCountryId; } + /** + * @return The country name + */ public String getCountry() { return mCountry; } @@ -103,6 +172,7 @@ public final class WeatherLocation implements Parcelable{ mKey = in.readInt(); mCityId = in.readString(); mCity = in.readString(); + mState = in.readString(); mPostal = in.readString(); mCountryId = in.readString(); mCountry = in.readString(); @@ -138,6 +208,7 @@ public final class WeatherLocation implements Parcelable{ dest.writeInt(mKey); dest.writeString(mCityId); dest.writeString(mCity); + dest.writeString(mState); dest.writeString(mPostal); dest.writeString(mCountryId); dest.writeString(mCountry); @@ -151,7 +222,8 @@ public final class WeatherLocation implements Parcelable{ return new StringBuilder() .append("{ City ID: ").append(mCityId) .append(" City: ").append(mCity) - .append(" Postal Code: ").append(mPostal) + .append(" State: ").append(mState) + .append(" Postal/ZIP Code: ").append(mPostal) .append(" Country Id: ").append(mCountryId) .append(" Country: ").append(mCountry).append("}") .toString(); diff --git a/system-api/cm_system-current.txt b/system-api/cm_system-current.txt index a00cf44..4c39eec 100644 --- a/system-api/cm_system-current.txt +++ b/system-api/cm_system-current.txt @@ -1391,6 +1391,7 @@ package cyanogenmod.weather { method public java.lang.String getCountry(); method public java.lang.String getCountryId(); method public java.lang.String getPostalCode(); + method public java.lang.String getState(); method public void writeToParcel(android.os.Parcel, int); field public static final android.os.Parcelable.Creator CREATOR; } @@ -1400,6 +1401,7 @@ package cyanogenmod.weather { method public cyanogenmod.weather.WeatherLocation build(); method public cyanogenmod.weather.WeatherLocation.Builder setCountry(java.lang.String, java.lang.String); method public cyanogenmod.weather.WeatherLocation.Builder setPostalCode(java.lang.String); + method public cyanogenmod.weather.WeatherLocation.Builder setState(java.lang.String); } }