From 4c1b079e05a9db1187ac11932be0499a22fd578b Mon Sep 17 00:00:00 2001 From: Alexey Zinchenko Date: Fri, 26 Mar 2021 02:20:19 +0300 Subject: [PATCH] Releasing 2.0.0 version. --- .github/workflows/codeql-analysis.yml | 4 +- README.md | 4 +- docs/SNAPSHOT.md | 257 +++++++++++++++++--------- pom.xml | 2 +- 4 files changed, 173 insertions(+), 94 deletions(-) diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index caceddf..7fb11b5 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -13,10 +13,10 @@ name: "CodeQL" on: push: - branches: [ dev ] + branches: [ master ] pull_request: # The branches below must be a subset of the branches above - branches: [ dev ] + branches: [ master ] schedule: - cron: '27 20 * * 1' diff --git a/README.md b/README.md index dbdc90e..77be6ea 100644 --- a/README.md +++ b/README.md @@ -26,14 +26,14 @@ Paid: com.github.prominence openweathermap-api - 2.0.0-SNAPSHOT + 2.0.0 ``` ### Gradle coordinates: ```groovy -compile('com.github.prominence:openweathermap-api:2.0.0-SNAPSHOT') +compile('com.github.prominence:openweathermap-api:2.0.0') ``` ### Documentation diff --git a/docs/SNAPSHOT.md b/docs/SNAPSHOT.md index 2461234..2027145 100644 --- a/docs/SNAPSHOT.md +++ b/docs/SNAPSHOT.md @@ -1,128 +1,207 @@ ### Implemented features: * Current weather data +* 5 day / 3-hour forecast + ### Maven coordinates: ```xml com.github.prominence openweathermap-api - 2.0-SNAPSHOT + 2.0.0-SNAPSHOT ``` ### Gradle coordinates: ```groovy -compile('com.github.prominence:openweathermap-api:2.0-SNAPSHOT') +compile('com.github.prominence:openweathermap-api:2.0.0-SNAPSHOT') ``` ### How to use: -Firstly, you need to create the instance of `OpenWeatherMapManager` class: +Firstly, you need to create the instance of `OpenWeatherMapClient` class: ```java OpenWeatherMapClient openWeatherClient = new OpenWeatherMapClient(API_TOKEN); ``` where `API_TOKEN` is your token([you can get it here](https://home.openweathermap.org/api_keys)) as `String`. -#### Current weather data -Current weather request chain structure: +Currently, available APIs are: +* `currentWeather()` +* `forecast5Day3HourStep()` + +Default(more or less) customization points: ```java -openWeatherClient - .currentWeather() - .() - . - . - ... - . - .() - .as(Java|JSON|XML|HTML)(); +... +// response language +.language(Language.RUSSIAN) +... +// response units of measure +.unitSystem(UnitSystem.IMPERIAL) +... ``` -Available methods for location selection for **single** result request: -* `byCityName(String cityName)` -* `byCityName(String cityName, String countryCode)` -* `byCityId(long cityId)` -* `byCoordinate(Coordinate coordinate)` -* `byZipCodeAndCountry(String zipCode, String countryCode)` +Available output forms: +* `asJava()` +* `asJSON()` -Available methods for location selection for **multiple** result request: -* `byRectangle(CoordinateRectangle rectangle, int zoom)` -* `byRectangle(CoordinateRectangle rectangle, int zoom, boolean useServerClustering)` -* `byCitiesInCycle(Coordinate point, int citiesCount)` -* `byCitiesInCycle(Coordinate point, int citiesCount, boolean useServerClustering)` +Additional output forms, available for several APIs: +* `asXML()` +* `asHTML()` + +_All response forms can be in **sync** and **async** variants._ + +#### Current weather data +Examples: +```java +final String weatherJson = openWeatherClient + .currentWeather() + .single() + .byCityName("Minsk") + .language(Language.RUSSIAN) + .unitSystem(UnitSystem.IMPERIAL) + .retrieve() + .asJSON(); +``` -Single location request examples: ```java final Weather weather = openWeatherClient - .currentWeather() - .single() - .byCoordinate(new Coordinate(5, 5)) - .accuracy(Accuracy.ACCURATE) - .language(Language.ROMANIAN) - .unitSystem(UnitSystem.METRIC) - .retrieve() - .asJava(); - -final CompletableFuture weatherXmlFuture = openWeatherClient - .currentWeather() - .single() - .byZipCodeAndCountry("220015", "by") - .language(Language.RUSSIAN) - .unitSystem(UnitSystem.METRIC) - .retrieveAsync() - .asXML(); + .currentWeather() + .single() + .byCityName("Minsk") + .language(Language.RUSSIAN) + .unitSystem(UnitSystem.METRIC) + .retrieve() + .asJava(); ``` -Multiple locations request examples: ```java -final String weatherListJson = openWeatherClient - .currentWeather() - .multiple() - .byRectangle(new CoordinateRectangle(12, 32, 15, 37), 10, true) - .accuracy(Accuracy.ACCURATE) - .language(Language.ROMANIAN) - .unitSystem(UnitSystem.METRIC) - .retrieve() - .asJSON(); - -final CompletableFuture> weatherListFuture = openWeatherClient - .currentWeather() - .multiple() - .byCitiesInCycle(new Coordinate(55.5, 37.5), 10, true) - .unitSystem(UnitSystem.IMPERIAL) - .retrieveAsync() - .asJava(); +final List weatherList = openWeatherClient + .currentWeather() + .multiple() + .byCitiesInCycle(Coordinate.withValues(55.5, 37.5)) + .language(Language.GERMAN) + .unitSystem(UnitSystem.IMPERIAL) + .retrieve() + .asJava(); ``` -`Weather`'s useful public methods(setters are not listed): +```java +final CompletableFuture weatherXmlFuture = openWeatherClient + .currentWeather() + .single() + .byZipCodeAndCountry("220015", "by") + .language(Language.RUSSIAN) + .unitSystem(UnitSystem.METRIC) + .retrieveAsync() + .asXML(); +``` -| Method | Description | -|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| `getWeatherState()` | Returns weather identifier. Example: `Clouds`, `Clear`. | -| `getWeatherDescription()` | Returns weather description. Example: `clear sky`. | -| `getWeatherIconUrl()` | Returns weather icon url. | -| `getRequestedOn()` | Returns `LocalDateTime` instance which represents date when request was made. | -| `getTemperature()` | Returns `Temperature` instance with temperature and max/min values. | -| `getPressure()` | Returns `Pressure` instance that contains information about atmosphericPressure and(not always) atmosphericPressure on ground/sea level. | -| `getHumidity()` | Returns `Humidity` instance that contains information about humidity. | -| `getWind()` | Returns `Wind` instance that contains *humidity* percentage information. | -| `getRain()` | Returns `Rain` instance that contains information about rain level for the last 1 and 3 hours. | -| `getSnow()` | Returns `Snow` instance that contains information about snow level for the last 1 and 3 hours. | -| `getClouds()` | Returns `Clouds` instance that contains *cloudiness* percentage information. | -| `getLocation()` | Returns `Location` instance that contains location information: coordinate, name and etc. | +You are able to set preferable options(via chain methods) and execute appropriate request. + +`com.github.prominence.openweathermap.api.model.weather.Weather`'s useful public methods(setters are not listed): + +| Method | Description | +|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `getState()` | Returns short weather description. Example: `Clear`. | +| `getDescription()` | Returns weather description. Example: `clear sky`. | +| `getWeatherIconUrl()` | Returns a link to weather icon hosted on https://openweathermap.org website. | +| `getCalculatedOn()` | Returns `LocalDateTime` object with data calculation time. | +| `getTemperature()` | Returns `Temperature` instance that contains information about temperature. Available fields: `value`, `maxTemperature`, `minTemperature`, `feelsLike` and `unit`. | +| `getAtmosphericPressure()`| Returns `AtmosphericPressure` instance that contains information about atmospheric pressure. Available fields: `value`, `seaLevelValue`, `groundLevelValue` and `unit`. | +| `getHumidity()` | Returns `Humidity` instance that contains humidity percentage information. | +| `getWind()` | Returns `Wind` instance that contains wind information: `speed`, `degrees`, `gust` and `unit`. | +| `getRain()` | Returns `Rain` instance that contains information about rain volume for the last one hour and/or the last 3 hours. Can be absent in case of no data. | +| `getSnow()` | Returns `Snow` instance that contains information about snow volume for the last one hour and/or the last 3 hours. Can be absent in case of no data. | +| `getClouds()` | Returns `Clouds` instance that contains information about cloudiness percentage. | +| `getLocation()` | Returns `Location` object. Available fields: `id`, `name`, `countryCode`, `sunrise` and `sunset` time, `zoneOffset` and `coordinate`. | +| `toString()` | Returns informative string for the whole available weather information. | `toString()` output example: ``` -Location: Minsk(BY), Weather: слегка облачно, 20.0 ℃, 1019.0 hPa, Clouds: 40% +Location: Minsk(BY), Weather: clear sky, -4.22 ℃, 1020.0 hPa, Clouds: 0% ``` -### Constants and options +#### 5 day / 3-hour forecast +Examples: +```java +final Forecast forecast = openWeatherClient + .forecast5Day3HourStep() + .byCityName("Minsk") + .language(Language.ENGLISH) + .unitSystem(UnitSystem.METRIC) + .count(15) + .retrieve() + .asJava(); +``` -#### Accuracy -| Constant | Description | -|--------------------|------------------| -| Accuracy.LIKE | Close result. | -| Accuracy.ACCURATE | Accurate result. | +```java +final String forecastJson = getClient() + .forecast5Day3HourStep() + .byCityName("New York", "NY", "US") + .language(Language.SPANISH) + .unitSystem(UnitSystem.IMPERIAL) + .count(15) + .retrieve() + .asJSON(); +``` + +```java +CompletableFuture forecastFuture = getClient() + .forecast5Day3HourStep() + .byCityId(350001514) + .language(Language.ENGLISH) + .unitSystem(UnitSystem.METRIC) + .count(15) + .retrieveAsync() + .asXML(); +``` + +```java +final String forecastXml = getClient() + .forecast5Day3HourStep() + .byZipCodeInUSA("10005") + .language(Language.ENGLISH) + .unitSystem(UnitSystem.METRIC) + .retrieve() + .asXML(); +``` + +You are able to set preferable options(via chain methods) and execute appropriate request. + +`com.github.prominence.openweathermap.api.request.forecast.free.Forecast`'s useful public methods(setters are not listed): + +| Method | Description | +|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| `getLocation()` | Returns `Location` object. Available fields: `id`, `name`, `countryCode`, `sunrise` and `sunset` time, `zoneOffset`, `coordinate` and `population`. | +| `getWeatherForecasts()` | Returns list of `WeatherForecast` objects with forecast information. | +| `toString()` | Returns informative string for the whole available forecast information. | + +`toString()` output example: +``` +A forecast for Minsk with 15 timestamps. +``` + +`com.github.prominence.openweathermap.api.model.forecast.WeatherForecast`'s useful public methods(setters are not listed): + +| Method | Description | +|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `getState()` | Returns short weather description. Example: `Clear`. | +| `getDescription()` | Returns weather description. Example: `clear sky`. | +| `getWeatherIconUrl()` | Returns a link to weather icon hosted on https://openweathermap.org website. | +| `getForecastTime()` | Returns `LocalDateTime` object with weather forecast time. | +| `getTemperature()` | Returns `Temperature` instance that contains information about temperature. Available fields: `value`, `maxTemperature`, `minTemperature`, `feelsLike` and `unit`. | +| `getAtmosphericPressure()` | Returns `AtmosphericPressure` instance that contains information about atmospheric pressure. Available fields: `value`, `seaLevelValue`, `groundLevelValue` and `unit`. | +| `getHumidity()` | Returns `Humidity` instance that contains humidity percentage information. | +| `getWind()` | Returns `Wind` instance that contains wind information: `speed`, `degrees` and `unit`. | +| `getRain()` | Returns `Rain` instance that contains information about rain volume for the last 3 hours. Can be absent in case of no data. | +| `getSnow()` | Returns `Snow` instance that contains information about snow volume for the last 3 hours. Can be absent in case of no data. | +| `getClouds()` | Returns `Clouds` instance that contains information about cloudiness percentage. | +| `getForecastTimeISO()` | Returns String with time of data forecasted, ISO, UTC. | +| `getDayTime()` | Returns enumerations representing the part of day(day, night). | +| `toString()` | Returns informative string for the forecast of particular timestamp. | + +### Constants and options #### Language | Constant | Description | @@ -164,11 +243,11 @@ Location: Minsk(BY), Weather: слегка облачно, 20.0 ℃, 1019.0 hPa, #### Unit | Constant | Description | |----------------------|------------------------------------------------| -| UnitSystem.METRIC | Celsius, meter/sec, hPa, mm(rain, snow). | -| UnitSystem.IMPERIAL | Fahrenheit, miles/hour, hPa, mm(rain, snow). | -| UnitSystem.STANDARD | Kelvin, meter/sec, hPa, mm(rain, snow) | +| Unit.METRIC_SYSTEM | Celsius, meter/sec, hPa, mm(rain, snow). | +| Unit.IMPERIAL_SYSTEM | Fahrenheit, miles/hour, hPa, mm(rain, snow). | +| Unit.STANDARD_SYSTEM | Kelvin, meter/sec, hPa, mm(rain, snow). | ### Dependencies -* com.fasterxml.jackson.core:jackson-databind:2.9.9 -* org.slf4j:slf4j-api:1.7.26 (*compile*) -* junit:junit:4.12 (*test*) \ No newline at end of file +* com.fasterxml.jackson.core:jackson-databind:2.12.2 +* org.slf4j:slf4j-api:1.7.30 (*compile*) +* junit:junit:4.13.1 (*test*) \ No newline at end of file diff --git a/pom.xml b/pom.xml index 6c2a7c2..5d60bd0 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ com.github.prominence openweathermap-api - 2.0.0-SNAPSHOT + 2.0.0 jar Java OpenWeatherMap API