Implemented Air Pollution retrieving.

docs/SNAPSHOT.md

@@ -3,6 +3,7 @@
 * 5 day / 3 hour forecast
 * 16 day / daily forecast
 * UV Index
+* Air Pollution
 
 ### Maven coordinates:
 
@@ -297,6 +298,40 @@ Available requests:
 Date: Tue Jul 31 15:00:00 MSK 2018, Ultraviolet value: 6.230000
 ```
 
+#### Air pollution
+
+First step is retrieving `AirPollutionRequester` instance:
+```java
+OpenWeatherMapManager openWeatherMapManager = new OpenWeatherMapManager(API_TOKEN);
+AirPollutionRequester requester = openWeatherMapManager.getAirPollutionRequester();
+```
+after you need to set coordinates, time frame, date and execute appropriate request:
+```
+DailyForecast forecastResponse = forecastRequester
+    .setCoordinates(0.0f, 10.0f)
+    .setTimeFrame(TimeFrame.YEAR)
+    .setDate(new Date())
+    .retrieve();
+```
+
+Available requests:
+* `retrieve()`
+
+`AirPollution`'s useful public methods(setters are not listed):
+
+| Method                    | Description                                                               |
+|---------------------------|---------------------------------------------------------------------------|
+| `getCoordinates()`        | Returns `Coordinates` instance.                                           |
+| `getLongitude()`          | Returns longitude.                                                        |
+| `airPollutionInfo()`      | Returns list of `AirPollution.AirPollutionInfo` instances.                |
+| `toString()`              | Returns pretty string for the whole available air pollution information.  |
+
+`toString()` output example:
+```
+AirPollution[Date: Tue Jul 24 01:04:40 MSK 2018; Coordinates: latitude=0.0, longitude=9.9955]
+[Value: 8.0347114E-8, Value: 9.5041536E-8, Value: 7.7667146E-8, Value: 7.251491E-8, Value: 5.899763E-8, Value: 1.9186361E-8, Value: 1.729535E-8, Value: 1.25645805E-8, Value: 3.0852514E-9]
+```
+
 ### Constants and options
 
 #### Accuracy

src/main/java/com/github/prominence/openweathermap/api/AirPollutionRequester.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2018 Alexey Zinchenko
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+package com.github.prominence.openweathermap.api;
+
+import com.github.prominence.openweathermap.api.constants.TimeFrame;
+import com.github.prominence.openweathermap.api.exception.DataNotFoundException;
+import com.github.prominence.openweathermap.api.exception.InvalidAuthTokenException;
+import com.github.prominence.openweathermap.api.model.Coordinates;
+import com.github.prominence.openweathermap.api.model.response.AirPollution;
+import com.github.prominence.openweathermap.api.utils.JSONUtils;
+import com.github.prominence.openweathermap.api.utils.RequestUtils;
+import com.github.prominence.openweathermap.api.utils.TimeFrameUtils;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.util.Date;
+
+public class AirPollutionRequester extends AuthenticationTokenBasedRequester {
+
+    private Coordinates coordinates;
+    private TimeFrame timeFrame;
+    private Date date;
+
+    AirPollutionRequester(String authToken) {
+        super(authToken);
+    }
+
+    public AirPollutionRequester setCoordinates(Coordinates coordinates) {
+        this.coordinates = coordinates;
+        return this;
+    }
+
+    public AirPollutionRequester setCoordinates(float latitude, float longitude) {
+        this.coordinates = new Coordinates(latitude, longitude);
+        return this;
+    }
+
+    public AirPollutionRequester setTimeFrame(TimeFrame timeFrame) {
+        this.timeFrame = timeFrame;
+        return this;
+    }
+
+    public AirPollutionRequester setDate(Date date) {
+        this.date = date;
+        return this;
+    }
+
+    public AirPollution retrieve() throws InvalidAuthTokenException, DataNotFoundException {
+        if (coordinates == null || timeFrame == null || date == null) {
+            throw new IllegalArgumentException("You must execute 'setCoordinates', 'setTimeFrame' and 'setDate' and least once.");
+        }
+
+        String requestParameters = String.format("%s,%s/%s.json", coordinates.getLatitude(), coordinates.getLongitude(), TimeFrameUtils.formatDate(date, timeFrame));
+
+        AirPollution airPollution = null;
+
+        try (InputStream response = executeRequest("pollution/v1/co/", requestParameters)) {
+            airPollution = (AirPollution) JSONUtils.parseJSON(response, AirPollution.class);
+        } catch (IOException ex) {
+            ex.printStackTrace();
+        }
+
+        return airPollution;
+    }
+
+    private InputStream executeRequest(String requestType, String requestSpecificParameters) throws MalformedURLException, InvalidAuthTokenException, DataNotFoundException {
+
+        String url = OPEN_WEATHER_BASE_URL + requestType +
+                requestSpecificParameters +
+                "?appid=" +
+                authToken;
+        return RequestUtils.executeGetRequest(new URL(url));
+    }
+
+}

src/main/java/com/github/prominence/openweathermap/api/AuthenticationTokenBasedRequester.java

@@ -25,7 +25,8 @@ package com.github.prominence.openweathermap.api;
 abstract class AuthenticationTokenBasedRequester {
 
     protected static final String OPEN_WEATHER_API_VERSION = "2.5";
-    protected static final String OPEN_WEATHER_API_URL = "http://api.openweathermap.org/data/" + OPEN_WEATHER_API_VERSION + "/";
+    protected static final String OPEN_WEATHER_BASE_URL = "http://api.openweathermap.org/";
+    protected static final String OPEN_WEATHER_API_URL = OPEN_WEATHER_BASE_URL + "data/" + OPEN_WEATHER_API_VERSION + "/";
 
     protected String authToken;
 

src/main/java/com/github/prominence/openweathermap/api/OpenWeatherMapManager.java

@@ -45,4 +45,8 @@ public class OpenWeatherMapManager {
     public UltravioletIndexRequester getUltravioletIndexRequester() {
         return new UltravioletIndexRequester(authToken);
     }
+
+    public AirPollutionRequester getAirPollutionRequester() {
+        return new AirPollutionRequester(authToken);
+    }
 }

src/main/java/com/github/prominence/openweathermap/api/constants/TimeFrame.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2018 Alexey Zinchenko
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+package com.github.prominence.openweathermap.api.constants;
+
+public enum TimeFrame {
+    YEAR,
+    MONTH,
+    DAY,
+    HOUR,
+    MINUTE,
+    SECOND
+}

src/main/java/com/github/prominence/openweathermap/api/model/response/AirPollution.java

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2018 Alexey Zinchenko
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+package com.github.prominence.openweathermap.api.model.response;
+
+import com.alibaba.fastjson.annotation.JSONField;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.text.ParseException;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.List;
+
+@EqualsAndHashCode
+public class AirPollution {
+
+    @Getter
+    @Setter
+    private String time;
+
+    @Getter
+    @Setter
+    @JSONField(name = "location")
+    private Coordinates coordinates;
+
+    @JSONField(name = "data")
+    @Getter
+    @Setter
+    private List<AirPollutionInfo> airPollutionInfo;
+
+    public Date getCalculationDate() {
+        SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
+        try {
+            return format.parse(time);
+        } catch (ParseException e) {
+            e.printStackTrace();
+        }
+        return null;
+    }
+
+    @Override
+    public String toString() {
+        return "AirPollution[Date: " + getCalculationDate() + "; Coordinates: " + coordinates + "]" + "\n" + airPollutionInfo;
+    }
+
+    @EqualsAndHashCode
+    public static class AirPollutionInfo {
+
+        @Getter
+        @Setter
+        private float precision;
+
+        @Getter
+        @Setter
+        private short pressure;
+
+        @Getter
+        @Setter
+        private float value;
+
+        @Override
+        public String toString() {
+            return "Value: " + value;
+        }
+    }
+
+    @EqualsAndHashCode
+    public static class Coordinates {
+
+        @Getter
+        @Setter
+        private float latitude;
+
+        @Getter
+        @Setter
+        private float longitude;
+
+        @Override
+        public String toString() {
+            return "latitude=" + latitude + ", longitude=" + longitude;
+        }
+    }
+}

src/main/java/com/github/prominence/openweathermap/api/utils/TimeFrameUtils.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2018 Alexey Zinchenko
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+package com.github.prominence.openweathermap.api.utils;
+
+import com.github.prominence.openweathermap.api.constants.TimeFrame;
+
+import java.text.SimpleDateFormat;
+import java.util.Date;
+
+public final class TimeFrameUtils {
+
+    private TimeFrameUtils() {
+
+    }
+
+    /*
+    2016-01-02T15:04:05Z
+    searches between 2016-01-02T15:04:05Z and 2016-01-02T15:04:05.9999Z
+    2016-01-02T15:04Z
+    searches between 2016-01-02T15:04:00Z and 2016-01-02T15:04:59.9999Z
+    2016-01-02T15Z
+    searches between 2016-01-02T15:00:00Z and 2016-01-02T15:59:59.9999Z
+    2016-01-02Z
+    searches between 2016-01-02T00:00:00Z and 2016-01-02T23:59:59.9999Z
+    2016-01Z
+    searches between 2016-01-01T00:00:00Z and 2016-12-31T23:59:59.9999Z
+    2016Z
+    searches between 2016-01-01T00:00:00Z and 2016-12-31T23:59:99.9999Z
+    */
+
+    public static String formatDate(Date date, TimeFrame timeFrame) {
+
+        SimpleDateFormat formatter;
+
+        switch (timeFrame) {
+            case YEAR:
+                formatter = new SimpleDateFormat("yyyy'Z'");
+                break;
+            case MONTH:
+                formatter = new SimpleDateFormat("yyyy-MM'Z'");
+                break;
+            case DAY:
+                formatter = new SimpleDateFormat("yyyy-MM-dd'Z'");
+                break;
+            case HOUR:
+                formatter = new SimpleDateFormat("yyyy-MM-dd'T'HH'Z'");
+                break;
+            case MINUTE:
+                formatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm'Z'");
+                break;
+            case SECOND:
+                formatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
+                break;
+            default:
+                formatter = new SimpleDateFormat("yyyy-MM'Z'");
+        }
+
+        return formatter.format(date);
+    }
+
+}