Wrote documentation.

This commit is contained in:
Alexey Zinchenko 2021-03-25 00:58:14 +03:00
parent cd263234bc
commit c68c6fd2b6
9 changed files with 335 additions and 112 deletions

View File

@ -2,6 +2,7 @@
Java API for OpenWeatherMap services.
### Implemented features:
Free:
* Current weather data
* 5 day / 3-hour forecast
@ -39,6 +40,7 @@ compile('com.github.prominence:openweathermap-api:2.0-SNAPSHOT')
* [OpenWeatherMap Java API - 1.0](docs/Release_1.0.md)
* [OpenWeatherMap Java API - 1.1](docs/Release_1.1.md)
* [OpenWeatherMap Java API - 1.2](docs/Release_1.2.md)
* [OpenWeatherMap Java API - 2.0.0](docs/Release_2.0.0.md)
* [OpenWeatherMap Java API - SNAPSHOT](docs/SNAPSHOT.md)
### License

253
docs/Release_2.0.0.md Normal file
View File

@ -0,0 +1,253 @@
### Implemented features:
* Current weather data
* 5 day / 3-hour forecast
### Maven coordinates:
```xml
<dependency>
<groupId>com.github.prominence</groupId>
<artifactId>openweathermap-api</artifactId>
<version>2.0.0</version>
</dependency>
```
### Gradle coordinates:
```groovy
compile('com.github.prominence:openweathermap-api:2.0.0')
```
### How to use:
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`.
Currently, available APIs are:
* `currentWeather()`
* `forecast5Day3HourStep()`
Default(more or less) customization points:
```java
...
// response language
.language(Language.RUSSIAN)
...
// response units of measure
.unitSystem(UnitSystem.IMPERIAL)
...
```
Available output forms:
* `asJava()`
* `asJSON()`
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();
```
```java
final Weather weather = openWeatherClient
.currentWeather()
.single()
.byCityName("Minsk")
.language(Language.RUSSIAN)
.unitSystem(UnitSystem.METRIC)
.retrieve()
.asJava();
```
```java
final List<Weather> weatherList = openWeatherClient
.currentWeather()
.multiple()
.byCitiesInCycle(Coordinate.forValues(55.5, 37.5))
.language(Language.GERMAN)
.unitSystem(UnitSystem.IMPERIAL)
.retrieve()
.asJava();
```
```java
final CompletableFuture<String> weatherXmlFuture = openWeatherClient
.currentWeather()
.single()
.byZipCodeAndCountry("220015", "by")
.language(Language.RUSSIAN)
.unitSystem(UnitSystem.METRIC)
.retrieveAsync()
.asXML();
```
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: clear sky, -4.22 ℃, 1020.0 hPa, Clouds: 0%
```
#### 5 day / 3-hour forecast
Examples:
```java
final Forecast forecast = openWeatherClient
.forecast5Day3HourStep()
.byCityName("Minsk")
.language(Language.ENGLISH)
.unitSystem(UnitSystem.METRIC)
.count(15)
.retrieve()
.asJava();
```
```java
final String forecastJson = getClient()
.forecast5Day3HourStep()
.byCityName("New York", "NY", "US")
.language(Language.SPANISH)
.unitSystem(UnitSystem.IMPERIAL)
.count(15)
.retrieve()
.asJSON();
```
```java
CompletableFuture<String> 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.
```
`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 |
|-----------------------------------|-------------------------------|
| Language.ARABIC | Arabic language. |
| Language.BULGARIAN | Bulgarian language. |
| Language.CATALAN | Catalan language. |
| Language.CZECH | Czech language. |
| Language.GERMAN | German language. |
| Language.GREEK | Greek language. |
| Language.ENGLISH | English language. |
| Language.PERSIAN | Persian (Farsi) language. |
| Language.FINNISH | Finnish language. |
| Language.FRENCH | French language. |
| Language.GALICIAN | Galician language. |
| Language.CROATIAN | Croatian language. |
| Language.HUNGARIAN | Hungarian language. |
| Language.ITALIAN | Italian language. |
| Language.JAPANESE | Japanese language. |
| Language.KOREAN | Korean language. |
| Language.LATVIAN | Latvian language. |
| Language.LITHUANIAN | Lithuanian language. |
| Language.MACEDONIAN | Macedonian language. |
| Language.DUTCH | Dutch language. |
| Language.POLISH | Polish language. |
| Language.PORTUGUESE | Portuguese language. |
| Language.ROMANIAN | Romanian language. |
| Language.RUSSIAN | Russian language. |
| Language.SWEDISH | Swedish language. |
| Language.SLOVAK | Slovak language. |
| Language.SLOVENIAN | Slovenian language. |
| Language.SPANISH | Spanish language. |
| Language.TURKISH | Turkish language. |
| Language.UKRANIAN | Ukrainian language. |
| Language.VIETNAMESE | Vietnamese language. |
| Language.CHINESE_SIMPLIFIED | Chinese Simplified language. |
| Language.CHINESE_TRADITIONAL | Chinese Traditional language. |
#### Unit
| Constant | Description |
|----------------------|------------------------------------------------|
| 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.12.2
* org.slf4j:slf4j-api:1.7.30 (*compile*)
* junit:junit:4.13.1 (*test*)

View File

@ -1,33 +0,0 @@
/*
* Copyright (c) 2021 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.enums;
@Deprecated
public enum TimeFrame {
YEAR,
MONTH,
DAY,
HOUR,
MINUTE,
SECOND
}

View File

@ -28,19 +28,20 @@ import java.time.LocalDateTime;
import java.util.Objects;
public class WeatherForecast {
private LocalDateTime forecastTime;
private Temperature temperature;
private AtmosphericPressure atmosphericPressure;
private Humidity humidity;
private String state;
private String description;
private String weatherIconUrl;
private Clouds clouds;
private LocalDateTime forecastTime;
private Temperature temperature;
private AtmosphericPressure atmosphericPressure;
private Humidity humidity;
private Wind wind;
private Snow snow;
private Rain rain;
private Snow snow;
private Clouds clouds;
private String forecastTimeISO;
private DayTime dayTime;
@ -60,6 +61,36 @@ public class WeatherForecast {
return new WeatherForecast(state, description);
}
public String getState() {
return state;
}
public void setState(String state) {
if (state == null) {
throw new IllegalArgumentException("State must be not null.");
}
this.state = state;
}
public String getDescription() {
return description;
}
public void setDescription(String description) {
if (description == null) {
throw new IllegalArgumentException("Description must be not null.");
}
this.description = description;
}
public String getWeatherIconUrl() {
return weatherIconUrl;
}
public void setWeatherIconUrl(String weatherIconUrl) {
this.weatherIconUrl = weatherIconUrl;
}
public LocalDateTime getForecastTime() {
return forecastTime;
}
@ -92,44 +123,6 @@ public class WeatherForecast {
this.humidity = humidity;
}
public String getState() {
return state;
}
public void setState(String state) {
if (state == null) {
throw new IllegalArgumentException("State must be not null.");
}
this.state = state;
}
public String getDescription() {
return description;
}
public void setDescription(String description) {
if (description == null) {
throw new IllegalArgumentException("Description must be not null.");
}
this.description = description;
}
public String getWeatherIconUrl() {
return weatherIconUrl;
}
public void setWeatherIconUrl(String weatherIconUrl) {
this.weatherIconUrl = weatherIconUrl;
}
public Clouds getClouds() {
return clouds;
}
public void setClouds(Clouds clouds) {
this.clouds = clouds;
}
public Wind getWind() {
return wind;
}
@ -138,6 +131,14 @@ public class WeatherForecast {
this.wind = wind;
}
public Rain getRain() {
return rain;
}
public void setRain(Rain rain) {
this.rain = rain;
}
public Snow getSnow() {
return snow;
}
@ -146,12 +147,12 @@ public class WeatherForecast {
this.snow = snow;
}
public Rain getRain() {
return rain;
public Clouds getClouds() {
return clouds;
}
public void setRain(Rain rain) {
this.rain = rain;
public void setClouds(Clouds clouds) {
this.clouds = clouds;
}
public String getForecastTimeISO() {
@ -175,24 +176,24 @@ public class WeatherForecast {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
WeatherForecast that = (WeatherForecast) o;
return Objects.equals(forecastTime, that.forecastTime) &&
return Objects.equals(state, that.state) &&
Objects.equals(description, that.description) &&
Objects.equals(weatherIconUrl, that.weatherIconUrl) &&
Objects.equals(forecastTime, that.forecastTime) &&
Objects.equals(temperature, that.temperature) &&
Objects.equals(atmosphericPressure, that.atmosphericPressure) &&
Objects.equals(humidity, that.humidity) &&
Objects.equals(state, that.state) &&
Objects.equals(description, that.description) &&
Objects.equals(weatherIconUrl, that.weatherIconUrl) &&
Objects.equals(clouds, that.clouds) &&
Objects.equals(wind, that.wind) &&
Objects.equals(snow, that.snow) &&
Objects.equals(rain, that.rain) &&
Objects.equals(snow, that.snow) &&
Objects.equals(clouds, that.clouds) &&
Objects.equals(forecastTimeISO, that.forecastTimeISO) &&
dayTime == that.dayTime;
}
@Override
public int hashCode() {
return Objects.hash(forecastTime, temperature, atmosphericPressure, humidity, state, description, weatherIconUrl, clouds, wind, snow, rain, forecastTimeISO, dayTime);
return Objects.hash(state, description, weatherIconUrl, forecastTime, temperature, atmosphericPressure, humidity, wind, rain, snow, clouds, forecastTimeISO, dayTime);
}
@Override

View File

@ -50,16 +50,16 @@ import java.time.LocalDateTime;
import java.util.Objects;
public class Weather {
private String state;
private String description;
private String weatherIconUrl;
private LocalDateTime requestedOn;
private LocalDateTime calculatedOn;
private Temperature temperature;
private AtmosphericPressure atmosphericPressure;
private Humidity humidity;
private Wind wind;
private Rain rain;
private Snow snow;
@ -112,12 +112,12 @@ public class Weather {
this.weatherIconUrl = weatherIconUrl;
}
public LocalDateTime getRequestedOn() {
return requestedOn;
public LocalDateTime getCalculatedOn() {
return calculatedOn;
}
public void setRequestedOn(LocalDateTime requestedOn) {
this.requestedOn = requestedOn;
public void setCalculatedOn(LocalDateTime calculatedOn) {
this.calculatedOn = calculatedOn;
}
public Temperature getTemperature() {
@ -192,7 +192,7 @@ public class Weather {
return Objects.equals(state, weather.state) &&
Objects.equals(description, weather.description) &&
Objects.equals(weatherIconUrl, weather.weatherIconUrl) &&
Objects.equals(requestedOn, weather.requestedOn) &&
Objects.equals(calculatedOn, weather.calculatedOn) &&
Objects.equals(temperature, weather.temperature) &&
Objects.equals(atmosphericPressure, weather.atmosphericPressure) &&
Objects.equals(humidity, weather.humidity) &&
@ -205,7 +205,7 @@ public class Weather {
@Override
public int hashCode() {
return Objects.hash(state, description, weatherIconUrl, requestedOn, temperature, atmosphericPressure, humidity, wind, rain, snow, clouds, location);
return Objects.hash(state, description, weatherIconUrl, calculatedOn, temperature, atmosphericPressure, humidity, wind, rain, snow, clouds, location);
}
@Override

View File

@ -121,7 +121,7 @@ public class CurrentWeatherResponseMapper implements ResponseMapper<Weather> {
final JsonNode dtNode = rootNode.get("dt");
if (dtNode != null) {
weather.setRequestedOn(LocalDateTime.ofInstant(Instant.ofEpochSecond(dtNode.asInt()), TimeZone.getDefault().toZoneId()));
weather.setCalculatedOn(LocalDateTime.ofInstant(Instant.ofEpochSecond(dtNode.asInt()), TimeZone.getDefault().toZoneId()));
}
return weather;

View File

@ -87,9 +87,9 @@ public class WeatherUnitTest {
public void whenSetRequestedOn_thenValueIsSet() {
final Weather weather = Weather.forValue("state", "desc");
final LocalDateTime now = LocalDateTime.now();
weather.setRequestedOn(now);
weather.setCalculatedOn(now);
Assert.assertEquals(now, weather.getRequestedOn());
Assert.assertEquals(now, weather.getCalculatedOn());
}
@Test
@ -244,11 +244,11 @@ public class WeatherUnitTest {
Assert.assertTrue(one.equals(two));
final LocalDateTime now = LocalDateTime.now();
one.setRequestedOn(now);
one.setCalculatedOn(now);
Assert.assertFalse(one.equals(two));
two.setRequestedOn(now);
two.setCalculatedOn(now);
Assert.assertTrue(one.equals(two));

View File

@ -55,7 +55,7 @@ public class MultipleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -95,7 +95,7 @@ public class MultipleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -150,7 +150,7 @@ public class MultipleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());

View File

@ -51,7 +51,7 @@ public class SingleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -116,7 +116,7 @@ public class SingleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -181,7 +181,7 @@ public class SingleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -245,7 +245,7 @@ public class SingleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -306,7 +306,7 @@ public class SingleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -368,7 +368,7 @@ public class SingleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());
@ -433,7 +433,7 @@ public class SingleResultCurrentWeatherIntegrationTest extends ApiTest {
Assert.assertNotNull(weather);
Assert.assertNotNull(weather.getState());
Assert.assertNotNull(weather.getDescription());
Assert.assertNotNull(weather.getRequestedOn());
Assert.assertNotNull(weather.getCalculatedOn());
Assert.assertNotNull(weather.getTemperature());
Assert.assertNotNull(weather.getLocation());
Assert.assertNotNull(weather.getAtmosphericPressure());