Skip to content

Commit 4c1b079

Browse files
ProminenceProminence
committed
Releasing 2.0.0 version.
1 parent 7ad0f9d commit 4c1b079

File tree

4 files changed

+177
-98
lines changed

4 files changed

+177
-98
lines changed

‎.github/workflows/codeql-analysis.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ name: "CodeQL"
1313

1414
on:
1515
push:
16-
branches: [ dev ]
16+
branches: [ master ]
1717
pull_request:
1818
# The branches below must be a subset of the branches above
19-
branches: [ dev ]
19+
branches: [ master ]
2020
schedule:
2121
- cron: '27 20 * * 1'
2222

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,14 @@ Paid:
2626
<dependency>
2727
<groupId>com.github.prominence</groupId>
2828
<artifactId>openweathermap-api</artifactId>
29-
<version>2.0.0-SNAPSHOT</version>
29+
<version>2.0.0</version>
3030
</dependency>
3131
```
3232

3333
### Gradle coordinates:
3434

3535
```groovy
36-
compile('com.github.prominence:openweathermap-api:2.0.0-SNAPSHOT')
36+
compile('com.github.prominence:openweathermap-api:2.0.0')
3737
```
3838

3939
### Documentation

‎docs/SNAPSHOT.md‎

Lines changed: 172 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,128 +1,207 @@
11
### Implemented features:
22
* Current weather data
3+
* 5 day / 3-hour forecast
4+
35
### Maven coordinates:
46

57
```xml
68
<dependency>
79
<groupId>com.github.prominence</groupId>
810
<artifactId>openweathermap-api</artifactId>
9-
<version>2.0-SNAPSHOT</version>
11+
<version>2.0.0-SNAPSHOT</version>
1012
</dependency>
1113
```
1214

1315
### Gradle coordinates:
1416

1517
```groovy
16-
compile('com.github.prominence:openweathermap-api:2.0-SNAPSHOT')
18+
compile('com.github.prominence:openweathermap-api:2.0.0-SNAPSHOT')
1719
```
1820

1921
### How to use:
2022

21-
Firstly, you need to create the instance of `OpenWeatherMapManager` class:
23+
Firstly, you need to create the instance of `OpenWeatherMapClient` class:
2224
```java
2325
OpenWeatherMapClient openWeatherClient = new OpenWeatherMapClient(API_TOKEN);
2426
```
2527
where `API_TOKEN` is your token([you can get it here](https://home.openweathermap.org/api_keys)) as `String`.
2628

29+
Currently, available APIs are:
30+
* `currentWeather()`
31+
* `forecast5Day3HourStep()`
32+
33+
Default(more or less) customization points:
34+
```java
35+
...
36+
// response language
37+
.language(Language.RUSSIAN)
38+
...
39+
// response units of measure
40+
.unitSystem(UnitSystem.IMPERIAL)
41+
...
42+
```
43+
44+
Available output forms:
45+
* `asJava()`
46+
* `asJSON()`
47+
48+
Additional output forms, available for several APIs:
49+
* `asXML()`
50+
* `asHTML()`
51+
52+
_All response forms can be in **sync** and **async** variants._
53+
2754
#### Current weather data
28-
Current weather request chain structure:
55+
Examples:
2956
```java
30-
openWeatherClient
31-
.currentWeather()
32-
.<single|multiple location(s)>()
33-
.<location definition>
34-
.<customize unitSystem/language/accuracy (1)>
35-
...
36-
.<customize unitSystem/language/accuracy (N)>
37-
.<request/requestAsync>()
38-
.as(Java|JSON|XML|HTML)();
39-
```
40-
41-
Available methods for location selection for **single** result request:
42-
* `byCityName(String cityName)`
43-
* `byCityName(String cityName, String countryCode)`
44-
* `byCityId(long cityId)`
45-
* `byCoordinate(Coordinate coordinate)`
46-
* `byZipCodeAndCountry(String zipCode, String countryCode)`
47-
48-
Available methods for location selection for **multiple** result request:
49-
* `byRectangle(CoordinateRectangle rectangle, int zoom)`
50-
* `byRectangle(CoordinateRectangle rectangle, int zoom, boolean useServerClustering)`
51-
* `byCitiesInCycle(Coordinate point, int citiesCount)`
52-
* `byCitiesInCycle(Coordinate point, int citiesCount, boolean useServerClustering)`
53-
54-
Single location request examples:
57+
final String weatherJson = openWeatherClient
58+
.currentWeather()
59+
.single()
60+
.byCityName("Minsk")
61+
.language(Language.RUSSIAN)
62+
.unitSystem(UnitSystem.IMPERIAL)
63+
.retrieve()
64+
.asJSON();
65+
```
66+
5567
```java
5668
final Weather weather = openWeatherClient
57-
.currentWeather()
58-
.single()
59-
.byCoordinate(new Coordinate(5, 5))
60-
.accuracy(Accuracy.ACCURATE)
61-
.language(Language.ROMANIAN)
62-
.unitSystem(UnitSystem.METRIC)
63-
.retrieve()
64-
.asJava();
69+
.currentWeather()
70+
.single()
71+
.byCityName("Minsk")
72+
.language(Language.RUSSIAN)
73+
.unitSystem(UnitSystem.METRIC)
74+
.retrieve()
75+
.asJava();
76+
```
77+
78+
```java
79+
final List<Weather> weatherList = openWeatherClient
80+
.currentWeather()
81+
.multiple()
82+
.byCitiesInCycle(Coordinate.withValues(55.5, 37.5))
83+
.language(Language.GERMAN)
84+
.unitSystem(UnitSystem.IMPERIAL)
85+
.retrieve()
86+
.asJava();
87+
```
6588

89+
```java
6690
final CompletableFuture<String> weatherXmlFuture = openWeatherClient
67-
.currentWeather()
68-
.single()
69-
.byZipCodeAndCountry("220015", "by")
70-
.language(Language.RUSSIAN)
71-
.unitSystem(UnitSystem.METRIC)
72-
.retrieveAsync()
73-
.asXML();
91+
.currentWeather()
92+
.single()
93+
.byZipCodeAndCountry("220015", "by")
94+
.language(Language.RUSSIAN)
95+
.unitSystem(UnitSystem.METRIC)
96+
.retrieveAsync()
97+
.asXML();
98+
```
99+
100+
You are able to set preferable options(via chain methods) and execute appropriate request.
101+
102+
`com.github.prominence.openweathermap.api.model.weather.Weather`'s useful public methods(setters are not listed):
103+
104+
| Method | Description |
105+
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
106+
| `getState()` | Returns short weather description. Example: `Clear`. |
107+
| `getDescription()` | Returns weather description. Example: `clear sky`. |
108+
| `getWeatherIconUrl()` | Returns a link to weather icon hosted on https://openweathermap.org website. |
109+
| `getCalculatedOn()` | Returns `LocalDateTime` object with data calculation time. |
110+
| `getTemperature()` | Returns `Temperature` instance that contains information about temperature. Available fields: `value`, `maxTemperature`, `minTemperature`, `feelsLike` and `unit`. |
111+
| `getAtmosphericPressure()`| Returns `AtmosphericPressure` instance that contains information about atmospheric pressure. Available fields: `value`, `seaLevelValue`, `groundLevelValue` and `unit`. |
112+
| `getHumidity()` | Returns `Humidity` instance that contains humidity percentage information. |
113+
| `getWind()` | Returns `Wind` instance that contains wind information: `speed`, `degrees`, `gust` and `unit`. |
114+
| `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. |
115+
| `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. |
116+
| `getClouds()` | Returns `Clouds` instance that contains information about cloudiness percentage. |
117+
| `getLocation()` | Returns `Location` object. Available fields: `id`, `name`, `countryCode`, `sunrise` and `sunset` time, `zoneOffset` and `coordinate`. |
118+
| `toString()` | Returns informative string for the whole available weather information. |
119+
120+
`toString()` output example:
121+
```
122+
Location: Minsk(BY), Weather: clear sky, -4.22 ℃, 1020.0 hPa, Clouds: 0%
123+
```
124+
125+
#### 5 day / 3-hour forecast
126+
Examples:
127+
```java
128+
final Forecast forecast = openWeatherClient
129+
.forecast5Day3HourStep()
130+
.byCityName("Minsk")
131+
.language(Language.ENGLISH)
132+
.unitSystem(UnitSystem.METRIC)
133+
.count(15)
134+
.retrieve()
135+
.asJava();
74136
```
75137

76-
Multiple locations request examples:
77138
```java
78-
final String weatherListJson = openWeatherClient
79-
.currentWeather()
80-
.multiple()
81-
.byRectangle(new CoordinateRectangle(12, 32, 15, 37), 10, true)
82-
.accuracy(Accuracy.ACCURATE)
83-
.language(Language.ROMANIAN)
84-
.unitSystem(UnitSystem.METRIC)
85-
.retrieve()
86-
.asJSON();
87-
88-
final CompletableFuture<List<Weather>> weatherListFuture = openWeatherClient
89-
.currentWeather()
90-
.multiple()
91-
.byCitiesInCycle(new Coordinate(55.5, 37.5), 10, true)
92-
.unitSystem(UnitSystem.IMPERIAL)
93-
.retrieveAsync()
94-
.asJava();
95-
```
96-
97-
`Weather`'s useful public methods(setters are not listed):
98-
99-
| Method | Description |
100-
|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
101-
| `getWeatherState()` | Returns weather identifier. Example: `Clouds`, `Clear`. |
102-
| `getWeatherDescription()` | Returns weather description. Example: `clear sky`. |
103-
| `getWeatherIconUrl()` | Returns weather icon url. |
104-
| `getRequestedOn()` | Returns `LocalDateTime` instance which represents date when request was made. |
105-
| `getTemperature()` | Returns `Temperature` instance with temperature and max/min values. |
106-
| `getPressure()` | Returns `Pressure` instance that contains information about atmosphericPressure and(not always) atmosphericPressure on ground/sea level. |
107-
| `getHumidity()` | Returns `Humidity` instance that contains information about humidity. |
108-
| `getWind()` | Returns `Wind` instance that contains *humidity* percentage information. |
109-
| `getRain()` | Returns `Rain` instance that contains information about rain level for the last 1 and 3 hours. |
110-
| `getSnow()` | Returns `Snow` instance that contains information about snow level for the last 1 and 3 hours. |
111-
| `getClouds()` | Returns `Clouds` instance that contains *cloudiness* percentage information. |
112-
| `getLocation()` | Returns `Location` instance that contains location information: coordinate, name and etc. |
139+
final String forecastJson = getClient()
140+
.forecast5Day3HourStep()
141+
.byCityName("New York", "NY", "US")
142+
.language(Language.SPANISH)
143+
.unitSystem(UnitSystem.IMPERIAL)
144+
.count(15)
145+
.retrieve()
146+
.asJSON();
147+
```
148+
149+
```java
150+
CompletableFuture<String> forecastFuture = getClient()
151+
.forecast5Day3HourStep()
152+
.byCityId(350001514)
153+
.language(Language.ENGLISH)
154+
.unitSystem(UnitSystem.METRIC)
155+
.count(15)
156+
.retrieveAsync()
157+
.asXML();
158+
```
159+
160+
```java
161+
final String forecastXml = getClient()
162+
.forecast5Day3HourStep()
163+
.byZipCodeInUSA("10005")
164+
.language(Language.ENGLISH)
165+
.unitSystem(UnitSystem.METRIC)
166+
.retrieve()
167+
.asXML();
168+
```
169+
170+
You are able to set preferable options(via chain methods) and execute appropriate request.
171+
172+
`com.github.prominence.openweathermap.api.request.forecast.free.Forecast`'s useful public methods(setters are not listed):
173+
174+
| Method | Description |
175+
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
176+
| `getLocation()` | Returns `Location` object. Available fields: `id`, `name`, `countryCode`, `sunrise` and `sunset` time, `zoneOffset`, `coordinate` and `population`. |
177+
| `getWeatherForecasts()` | Returns list of `WeatherForecast` objects with forecast information. |
178+
| `toString()` | Returns informative string for the whole available forecast information. |
113179

114180
`toString()` output example:
115181
```
116-
Location: Minsk(BY), Weather: слегка облачно, 20.0 ℃, 1019.0 hPa, Clouds: 40%
182+
A forecast for Minsk with 15 timestamps.
117183
```
118184

119-
### Constants and options
185+
`com.github.prominence.openweathermap.api.model.forecast.WeatherForecast`'s useful public methods(setters are not listed):
186+
187+
| Method | Description |
188+
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
189+
| `getState()` | Returns short weather description. Example: `Clear`. |
190+
| `getDescription()` | Returns weather description. Example: `clear sky`. |
191+
| `getWeatherIconUrl()` | Returns a link to weather icon hosted on https://openweathermap.org website. |
192+
| `getForecastTime()` | Returns `LocalDateTime` object with weather forecast time. |
193+
| `getTemperature()` | Returns `Temperature` instance that contains information about temperature. Available fields: `value`, `maxTemperature`, `minTemperature`, `feelsLike` and `unit`. |
194+
| `getAtmosphericPressure()` | Returns `AtmosphericPressure` instance that contains information about atmospheric pressure. Available fields: `value`, `seaLevelValue`, `groundLevelValue` and `unit`. |
195+
| `getHumidity()` | Returns `Humidity` instance that contains humidity percentage information. |
196+
| `getWind()` | Returns `Wind` instance that contains wind information: `speed`, `degrees` and `unit`. |
197+
| `getRain()` | Returns `Rain` instance that contains information about rain volume for the last 3 hours. Can be absent in case of no data. |
198+
| `getSnow()` | Returns `Snow` instance that contains information about snow volume for the last 3 hours. Can be absent in case of no data. |
199+
| `getClouds()` | Returns `Clouds` instance that contains information about cloudiness percentage. |
200+
| `getForecastTimeISO()` | Returns String with time of data forecasted, ISO, UTC. |
201+
| `getDayTime()` | Returns enumerations representing the part of day(day, night). |
202+
| `toString()` | Returns informative string for the forecast of particular timestamp. |
120203

121-
#### Accuracy
122-
| Constant | Description |
123-
|--------------------|------------------|
124-
| Accuracy.LIKE | Close result. |
125-
| Accuracy.ACCURATE | Accurate result. |
204+
### Constants and options
126205

127206
#### Language
128207
| Constant | Description |
@@ -164,11 +243,11 @@ Location: Minsk(BY), Weather: слегка облачно, 20.0 ℃, 1019.0 hPa,
164243
#### Unit
165244
| Constant | Description |
166245
|----------------------|------------------------------------------------|
167-
| UnitSystem.METRIC | Celsius, meter/sec, hPa, mm(rain, snow). |
168-
| UnitSystem.IMPERIAL | Fahrenheit, miles/hour, hPa, mm(rain, snow). |
169-
| UnitSystem.STANDARD | Kelvin, meter/sec, hPa, mm(rain, snow) |
246+
| Unit.METRIC_SYSTEM | Celsius, meter/sec, hPa, mm(rain, snow). |
247+
| Unit.IMPERIAL_SYSTEM | Fahrenheit, miles/hour, hPa, mm(rain, snow). |
248+
| Unit.STANDARD_SYSTEM | Kelvin, meter/sec, hPa, mm(rain, snow). |
170249

171250
### Dependencies
172-
* com.fasterxml.jackson.core:jackson-databind:2.9.9
173-
* org.slf4j:slf4j-api:1.7.26 (*compile*)
174-
* junit:junit:4.12 (*test*)
251+
* com.fasterxml.jackson.core:jackson-databind:2.12.2
252+
* org.slf4j:slf4j-api:1.7.30 (*compile*)
253+
* junit:junit:4.13.1 (*test*)

‎pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
<groupId>com.github.prominence</groupId>
88
<artifactId>openweathermap-api</artifactId>
9-
<version>2.0.0-SNAPSHOT</version>
9+
<version>2.0.0</version>
1010
<packaging>jar</packaging>
1111

1212
<name>Java OpenWeatherMap API</name>

0 commit comments

Comments
 (0)