Commit a2d6685f authored by Christopher Bohn's avatar Christopher Bohn 🤔
Browse files

Corrected JavaDoc omissions

parent d4a496fc
# JSON Connections for Files and REST APIs
# OpenWeather Connector
## With an enclosing connector for OpenWeather data
REpresentational State Transfer APIs (also known as REST APIs, RESTful APIs, or
RESTful web services) are a mechanism to request data from and send data to
remote servers without maintaining active, stateful connections over a
possibly-unreliable network. The
`edu.unl.cse.soft160.json_connections.connection.RestConnection` class is
sufficient to request data from a RESTful service.
The `edu.unl.cse.soft160.json_connections.connection.FileConnection` class
offers the same interface for requesting data, except that the data will be
found on the local file system. `FileConnection` can also save data to a file
which can be used to save data retrieved from a server using `RestConnection`
to be used later.
The `edu.unl.cse.soft160.json_connections.connector.OpenWeatherConnector` class
provides a wrapper for `RestConnection` and `FileConnection` to simplify client
code that uses data from [OpenWeathermap.org](https://openweathermap.org).
### Instructions to use `OpenWeatherConnector`
## Instructions to use `OpenWeatherConnector`
1. Obtain an API key from OpenWeathermap.org by
[signing up](https://home.openweathermap.org/users/sign_up) for a free
......@@ -41,20 +22,22 @@ code that uses data from [OpenWeathermap.org](https://openweathermap.org).
this.
- Do NOT place your API key in `apikeys.json-TEMPLATE`, or you will cause
your API key to be present in your repository.
3. When creating an `OpenWeatherConnector` object, if it should connect to the
local file system, then use the single-argument constructor, using "weather",
"onecall", "forecast", or "air_pollution" as the argument (or another
subdirectory of `src/main/resources/` that is named after one of the data
sets provided by the
[OpenWeathermap.org API](https://openweathermap.org/api)).
3. You may wish to review `edu.unl.cse.soft160.json_connections.Demonstration`
to see example uses of `OpenWeatherConnector`.
4. When creating an `OpenWeatherConnector` object, if it should connect to the
local file system, then use the single-argument constructor, using "weather",
"onecall", "forecast", "air_pollution", "air_pollution/history", or
"air_pollution/forecast" as the argument (or another subdirectory of
`src/main/resources/` that is named after one of the data sets provided by
the [OpenWeather API](https://openweathermap.org/api)).
5. When creating an `OpenWeatherConnector` object, if it should connect to the
OpenWeathermap.org RESTful service, use the two-argument constructor. The
first argument needs to be one of the data sets provided by the
[OpenWeathermap.org API](https://openweathermap.org/api), and the second
[OpenWeather API](https://openweathermap.org/api), and the second
argument needs to be the user's API key. Do not hard-code an API key.
Instead, Call `RestConnection.getApiKey("openweathermap")` to obtain the
API key from `apikeys.json` or prompt the user to enter their API key.
5. You *must* invoke an `OpenWeatherConnector` object's `retrieveData(String)`
6. You *must* invoke an `OpenWeatherConnector` object's `retrieveData(String)`
method before invoking any of its other non-constructor methods to obtain
the data that the other methods will use. You *may* make additional calls to
`retrieveData(String)` to replace the data with other data.
......@@ -64,21 +47,70 @@ code that uses data from [OpenWeathermap.org](https://openweathermap.org).
- If the `OpenWeatherConnector` instance is connected to OpenWeathermap.org
RESTful service, then the argument is the query string to be sent to
the RESTful service. See the
[OpenWeathermap.org API specification](https://openweathermap.org/api) for
details.
- [*"weather"*](https://openweathermap.org/current), the current weather
data set
- [*"onecall"*](https://openweathermap.org/api/one-call-api), the "One
Call API" data set
- [*forecast*](https://openweathermap.org/forecast5), the 5-day/3-hour
forecast data set
- [*air_pollution*](https://openweathermap.org/api/air-pollution), the air
quality and pollution data set
- Includes *air_pollution/forecast* and *air_pollution/history*
6. The remaining `OpenWeatherConnector` methods provide typed values for the
[OpenWeather API specification](https://openweathermap.org/api) for
details.
- Pay particular attention to option to specify the system of measurements
in the query, and which data are available only in one unit of measure.
- Here are links to the query details for specific data sets:
- [*"weather"*](https://openweathermap.org/current), the current weather
data set
- [*"onecall"*](https://openweathermap.org/api/one-call-api), the "One
Call API" data set
- [*forecast*](https://openweathermap.org/forecast5), the 5-day/3-hour
forecast data set
- [*air_pollution*](https://openweathermap.org/api/air-pollution), the air
quality and pollution data set
- Includes *air_pollution/forecast* and *air_pollution/history*
7. The remaining `OpenWeatherConnector` methods provide typed values for the
JSON fields in the data loaded by `retrieveData(String)`.
### Limitations
## Use in Your Project
### JavaDoc
You can generate the JavaDoc pages for publicly-accessible elements by invoking
the `javadoc:javadoc` Maven target from your IDE or from the command line:
```
mvn javadoc:javadoc
```
Open the file `target/site/apidocs/index.html` in your web browser to use the
JavaDoc pages.
### Copying files into your project
If you copy the classes and interface from this project into your own, be sure
that:
- You copy the fields into the same directories, *i.e.*:
- `src/main/java/edu/unl/cse/soft160/json_connections/connection/Connection.java`
- `src/main/java/edu/unl/cse/soft160/json_connections/connection/FileConnection.java`
- `src/main/java/edu/unl/cse/soft160/json_connections/connection/RestConnection.java`
- `src/main/java/edu/unl/cse/soft160/json_connections/connector/OpenWeatherConnector.java`
- `src/main/resources/apikeys-TEMPLATE.json`
- `src/main/resources/.gitignore` (this file prevents `apikeys.json` from
being committed to your repository)
- Your `pom.xml` file specifies the appropriate plugins and dependencies
- Your `pom.xml` file specifies Java version 11 or later
```xml
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>11</source>
<target>11</target>
</configuration>
</plugin>
```
- Your `pom.xml` file includes a dependency for
[JSON.simple](https://mvnrepository.com/artifact/com.googlecode.json-simple/json-simple)
```xml
<dependency>
<groupId>com.googlecode.json-simple</groupId>
<artifactId>json-simple</artifactId>
<version>1.1.1</version>
</dependency>
```
## Limitations
- `OpenWeatherConnector` only supports the free, no-cost APIs provided by
[OpenWeathermap.org](https://openweathermap.org). We do not have plans to
......@@ -101,22 +133,21 @@ code that uses data from [OpenWeathermap.org](https://openweathermap.org).
into question the assumption that a 3-hour value will be reported when rain
has fallen for more than an hour (or even more than three hours)
### Use in Your Project
#### JavaDoc
## JSON Connections for Files and REST APIs
You can generate the JavaDoc pages for publicly-accessible elements by invoking
the `javadoc:javadoc` Maven target from your IDE or from the command line:
```
mvn javadoc:javadoc
```
Open the file `target/site/apidocs/index.html` in your web browser to use the
JavaDoc pages.
REpresentational State Transfer APIs (also known as REST APIs, RESTful APIs, or
RESTful web services) are a mechanism to request data from and send data to
remote servers without maintaining active, stateful connections over a
possibly-unreliable network. The
`edu.unl.cse.soft160.json_connections.connection.RestConnection` class is
sufficient to request data from a RESTful service.
#### Maven notes
The `edu.unl.cse.soft160.json_connections.connection.FileConnection` class
offers the same interface for requesting data, except that the data will be
found on the local file system. `FileConnection` can also save data to a file
which can be used to save data retrieved from a server using `RestConnection`
to be used later.
If you copy the classes and interface from this project into your own, be sure
that:
- Your `pom.xml` file specifies Java version 11 or later
- Your `pom.xml` file includes a dependency for
[JSON.simple](https://mvnrepository.com/artifact/com.googlecode.json-simple/json-simple)
\ No newline at end of file
The `edu.unl.cse.soft160.json_connections.connector.OpenWeatherConnector` class
provides a wrapper for `RestConnection` and `FileConnection` to simplify client
code that uses data from [OpenWeathermap.org](https://openweathermap.org).
\ No newline at end of file
......@@ -56,7 +56,11 @@ public class OpenWeatherConnector {
}
/**
* <p>Air Quality Indices reported in OpenWeather air pollution reports.</p>
* <p>Air Quality Indices reported in OpenWeather air pollution reports. Note that while openweathermap.org refers
* to the Air Quality Indices on a scale of Good (1) to Very Poor (5), the CAQI Air Quality Index report refers to
* the Air Quality Indices as a level of pollutants on a scale of Very Low (1) to Very High (5). Numerically they
* are equivalent but the English-language meaning is different. This enumerated type uses the CAQI
* nomenclature.</p>
*
* <p>(n.b., {@link AirQuality#UNKNOWN_AIR_QUALITY} is a catch-all when no air quality data is present.)</p>
*
......@@ -342,8 +346,6 @@ public class OpenWeatherConnector {
* <p>Available for all datasets.</p>
*
* @return location's latitude
* @see #getLongitude()
* @see #getTimestamp()
*/
public double getLatitude() {
checkForDataReadiness(null);
......@@ -363,8 +365,6 @@ public class OpenWeatherConnector {
* <p>Available for all datasets.</p>
*
* @return location's longitude
* @see #getLatitude()
* @see #getTimestamp()
*/
public double getLongitude() {
checkForDataReadiness(null);
......@@ -385,8 +385,6 @@ public class OpenWeatherConnector {
* <p>Available for all datasets with data for the present.</p>
*
* @return timestamp for the weather observations
* @see #getLatitude()
* @see #getLongitude()
*/
public Date getTimestamp() {
checkForDataReadiness(null);
......@@ -415,7 +413,7 @@ public class OpenWeatherConnector {
* <p>Provides all dates and times for reports with multiple timestamps.</p>
* <p>Available for all datasets with data in the past or the future.</p>
*
* @throws IllegalStateException if no data has been retrieved using {@link #retrieveData(String)}
* @return list of timestamps for the weather observations
*/
public List<Date> getTimestamps() {
checkForDataReadiness(null);
......@@ -433,7 +431,7 @@ public class OpenWeatherConnector {
* <p>Available for all datasets with data in the past or the future.</p>
*
* @param listName the name of the list whose timestamps are of interest
* @throws IllegalStateException if no data has been retrieved using {@link #retrieveData(String)}
* @return list of timestamps for the weather observations
*/
public List<Date> getTimestamps(String listName) {
checkForDataReadiness(null);
......@@ -1102,6 +1100,7 @@ public class OpenWeatherConnector {
* timestamp.</p>
* <p>Available for the "onecall" (hourly only) dataset.</p>
*
* @param timestamp the timestamp for the forecasted rainfall
* @return the forecasted one-hour rainfall total, or 0.0 if rain volume is not in the forecast
*/
public double getOneHourRainfall(Date timestamp) {
......@@ -1125,6 +1124,7 @@ public class OpenWeatherConnector {
* timestamp.</p>
* <p>Available for the "forecast" dataset.</p>
*
* @param timestamp the timestamp for the forecasted rainfall
* @return the forecasted three-hour rainfall total, or 0.0 if rain volume is not in the forecast
*/
public double getThreeHourRainfall(Date timestamp) {
......@@ -1149,6 +1149,7 @@ public class OpenWeatherConnector {
* timestamp.</p>
* <p>Available for the "onecall" (hourly only) dataset.</p>
*
* @param timestamp the timestamp for the forecasted snowfall
* @return the forecasted one-hour rainfall total, or 0.0 if rain volume is not in the forecast
*/
public double getOneHourSnowfall(Date timestamp) {
......@@ -1172,6 +1173,7 @@ public class OpenWeatherConnector {
* timestamp.</p>
* <p>Available for the "forecast" dataset.</p>
*
* @param timestamp the timestamp for the forecasted snowfall
* @return the forecasted three-hour snowfall total, or 0.0 if snow volume is not in the forecast
*/
public double getThreeHourSnowfall(Date timestamp) {
......@@ -1185,6 +1187,7 @@ public class OpenWeatherConnector {
* snow.</p>
* <p>Available for the "onecall" dataset.</p>
*
* @param timestamp the timestamp for the forecasted precipitation
* @return the forecasted precipitation total, or 0.0 if precipitation volume is not in the forecast
*/
public double getMinutelyPrecipitation(Date timestamp) {
......@@ -1197,6 +1200,7 @@ public class OpenWeatherConnector {
* API specification, this appears to be a daily total.</p>
* <p>Available for the "onecall" dataset.</p>
*
* @param timestamp the timestamp for the forecasted rainfall
* @return the forecasted rain total, or 0.0 if precipitation volume is not in the forecast
*/
public double getDailyRainfall(Date timestamp) {
......@@ -1209,6 +1213,7 @@ public class OpenWeatherConnector {
* API specification, this appears to be a daily total.</p>
* <p>Available for the "onecall" dataset.</p>
*
* @param timestamp the timestamp for the forecasted snowfall
* @return the forecasted snow total, or 0.0 if precipitation volume is not in the forecast
*/
public double getDailySnowfall(Date timestamp) {
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment