ENGLISH VERSION

OpenWeatherApplication

INTRODUCTION

This file README.md aims to present and explain step by step the development of the exam project of *Object-Oriented Programming* for the session of January 24, 2022.

The main purpose of this project is to develop a Java application that makes a comparative analysis of statistical data (minimum, maximum, average and variance values of perceived and effective temperature values) concerning the weather information of two cities entered by the user via the terminal.

API

The implemented API is **Current OpenWeather**, and the call to this API has the following structure:

https://api.openweathermap.org/data/2.5/weather?q={city%20name}&appid={API%20key}

• {city%20name} represents the name of the city;
• {API%20key} represents the code needed to access the OpenWeather service.

E.g. By calling the API through the HTTP GET method:

https://api.openweathermap.org/data/2.5/weather?q=roma&appid={API%20key}

you get the following data in .json format.

{
"coord": {
"lon": 12.4839,
"lat": 41.8947
},
"weather": [
{
"id": 800,
"main": "Clear",
"description": "clear sky",
"icon": "01d"
}
],
"base": "stations",
"main": {
"temp": 287,
"feels_like": 285.98,
"temp_min": 284.89,
"temp_max": 289.07,
"pressure": 1024,
"humidity": 59
},
"visibility": 10000,
"wind": {
"speed": 0.51,
"deg": 0
},
"clouds": {
"all": 0
},
"dt": 1642346153,
"sys": {
"type": 2,
"id": 2037790,
"country": "IT",
"sunrise": 1642314890,
"sunset": 1642349055
},
"timezone": 3600,
"id": 6539761,
"name": "Roma",
"cod": 200
}

Thanks to the use of this API it was possible to obtain the live data necessary for our project:

• name name of the city requested
• main which contains:
  • temp current temperature
  • feels_like perceived temperature
  • temp_min minimum temperature
  • temp_max maximum temperature

RUNNING

The three main functionality are:

• provide single and comparative statistics of the cities entered by the user;
• save the data obtained in the appropriate .json format file;
• return the data collected in a specific period of time chosen by the user.

The operating mechanism of the program is as follows:

1. the Menu class, interfacing with the user via the terminal, collects the data entered by him (the names of the cities);

2. the CityServiceImpl.inputCity(...) method, defined by the CityService interface, uses the data entered by the user to send requests through URI calls, using the OpenWeather API, and receive "in response" the statistics of the cities chosen in .json format;

3. the ParseJSONDocument class parses the JSONObject, received by the CityServiceImpl.inputCity(...) method, and returns the "parsed" data via the terminal.

4. the CreatingJSONDocument class creates (or updates) the .json file by entering the values obtained from the class described in point 3. It acts as a database, containing all the statistics of the cities requested by the user;

5. the classes contained in the stats package are used to save and compare the obtained data.

6. finally, the classes contained in the filters package, through a request, made by the terminal (entering two dates), filter the collected data.

(JSON File example)

ADDITIONAL NOTES:

I. In case you want to filter without any research, data have been made available (to be imported into the FileCities.json file) in the Cities.json file in the folder JsonFile;

II. As an additional implementation, the user was given the possibility to enter cities and request the related statistics via HTTP requests.

This implementation is present in the controller package:

Roots	Description
/cities	GET: returns the name of all the cities entered (in addition to the first two generated by default); POST: allows you to enter, and then save, the name of a city
/cities/{id}	PUT: allows you to update the name of a city using its unique {id} DELETE: allows you to delete the name of a city using its unique {id}
/cities/names	POST: allows you to enter the name of the two cities for which you want the statistics
/cities/metadata	GET: returns the data collected in the previous calls (saved in a dedicated .json file)

Examples

(Example-POST root /cities/names)

(Example-GET root /cities/metadata)

HOW TO USE

To use this program you must first clone this repository locally and import the Open-Weather_Project project into the IntelliJ IDE (recommended).

To start the program select Open-Weather_Project in your package explorer and issue the command Run 'OWPSpringBootApplication'.

Once the program has been started, follow the instructions provided by the terminal menu.

POSSIBLE APPLICATIONS

The possible customers who can take advantage of this application are all those individuals / companies whose work is directly or indirectly linked to weather conditions, in particular to temperature.

Examples include agricultural businesses, sectors linked to tourism (travel agencies, ski resorts, etc.), and also research centers (monitoring of climate change, rising seas, etc.).

USED TOOLS (SOFTWARES & LIBRARIES)

• IDE IntelliJ to create the assigned project;
• PostMan to test and finally call the API used (Current OpenWeather);
• Editor Markdown Monster to write the README.md;
• Git and GitHub for code versioning;
• Spring Framework, and in particular Spring Boot, to speed up the development of the project;
• JUnit 5 Framework to test the functioning of the various components of the project;
• JavaDoc, to automatically generate the documentation of the source code (written in Java);
• org.json library to parse and generate Json files;
• Apache Maven library for dependency management;

AUTHORS & CONTRIBUTIONS

• Piercecchi Gabriel (50%): implementation of packages service, menu, controller, and partly utility (ParseJSONDocument class) and model (City class);
• Rossi Alan (50%): implementation of packages stats, filters And the remaining classes in utilities and model (JSONStructure class).

VERSIONE ITALIANA

OpenWeatherApplication

INTRODUZIONE

Questo file README.md ha lo scopo di presentare e spiegare passo dopo passo lo sviluppo del progetto d'esame di *Programmazione a Oggetti* per la sessione del 24 gennaio 2022.

L'obbiettivo principale di questo progetto consiste nello sviluppo di un'applicazione Java che esegua un'analisi comparativa dei dati statistici (valori minimo, massimo, medio e varianza dei valori di temperatura percepita ed effettiva) relativi alle informazioni meteorologiche di due città inserite dall'utente tramite il terminale.

API

L'API implementata è **Current OpenWeather**, e la chiamata a tale API presenta la seguente struttura:

https://api.openweathermap.org/data/2.5/weather?q={city%20name}&appid={API%20key}

• {city%20name} rappresenta il nome della città;
• {API%20key} rappresenta il codice necessario ad accedere al servizio OpenWeather.

Esempio

Richiamando attraverso il metodo HTTP GET l'API:

https://api.openweathermap.org/data/2.5/weather?q=roma&appid={API%20key}

si ottengono i seguenti dati sotto formato json

{
"coord": {
"lon": 12.4839,
"lat": 41.8947
},
"weather": [
{
"id": 800,
"main": "Clear",
"description": "clear sky",
"icon": "01d"
}
],
"base": "stations",
"main": {
"temp": 287,
"feels_like": 285.98,
"temp_min": 284.89,
"temp_max": 289.07,
"pressure": 1024,
"humidity": 59
},
"visibility": 10000,
"wind": {
"speed": 0.51,
"deg": 0
},
"clouds": {
"all": 0
},
"dt": 1642346153,
"sys": {
"type": 2,
"id": 2037790,
"country": "IT",
"sunrise": 1642314890,
"sunset": 1642349055
},
"timezone": 3600,
"id": 6539761,
"name": "Roma",
"cod": 200
}

Grazie all'utilizzo di quest'api è stato possibile ottenere i dati live necessari per il nostro progetto:

• name nome della città richiesta
• main che contiene:
  • temp temperatura corrente
  • feels_like temperatura percepita
  • temp_min temperatura minima
  • temp_max temperatura massima

RUNNING

Le tre funzionalità principali sono:

• fornire le statistiche singole e comparate delle città inserite dall'utente;
• salvare i dati ottenuti nell'apposito file formato .json;
• restituire i dati collezionati in un determinato periodo di tempo scelto dall'utente.

Il meccanismo di funzionamento del programma è il seguente:

1. la classe Menu, interfacciandosi con l'utente tramite terminale, raccoglie i dati da lui inseriti (i nomi delle città);

2. il metodo CityServiceImpl.inputCity(...), definito dall'interfaccia CityService, utilizza i dati inseriti dall'utente per inviare delle richieste tramite delle chiamate URI, sfruttando l'API OpenWeather, e ricevere "in risposta" le statistiche delle città scelte in formato .json;

3. la classe ParseJSONDocument effettua il parsing del JSONObject, ricevuto dal metodo CityServiceImpl.inputCity(...), e restituisce tramite terminale i dati "parsati".

4. la classe CreatingJSONDocument crea, o aggiorna, il file .json inserendo i valori ottenuti dalla classe descritta al punto TRE. Esso funge da database di tutte le città, con le corrispettive statistiche, richieste dall'utente;

5. le classi e l'interfaccia contenute nel package stats servono per salvare e confrontare i dati ottenuti.

6. infine le classi e l'interfaccia contenute nel package filters, tramite una richiesta fatta nell'interfaccia del menù (inserimento di due date), filtrano i dati collezionati.

(JSON File example)

NOTE AGGIUNTIVE:

I. Nel caso in cui si volesse effettuare il filtraggio senza nessuna ricerca sono stati messi a disposizione dei dati (da importare nel file FileCities.json) nel file Cities.json presente nella cartella JsonFile;

II. Come implementazione aggiuntiva è stata fornita all'utente la possibilità d'inserire le città e richiedere le relative statistiche tramite richieste HTTP.

Questa implementazione è rappresentata dal package controller:

Roots	Description
/cities	GET: restituisce il nome di tutte le città inserite (oltre alle prime due di default); POST: permette di inserire, e successivamente salvare, il nome di una città
/cities/{id}	PUT: permette di aggiornare il nome di una città sfruttando il suo {id} univoco DELETE: permette di eliminare il nome di una città sfruttando il suo {id} univoco
/cities/names	POST: permette di inserire il nome delle due città di cui si vogliono le statistiche
/cities/metadata	GET: restituisce i dati collezionati nelle chiamate precedenti (salvati in un file .json dedicato)

Esempi

(Esempio-POST indirizzo /cities/names)

(Esempio-GET indirizzo /cities/metadata)

COME SI USA

Per usare questo programma bisogna innanzitutto clonare questa repository in locale e importare il progetto Open-Weather_Project nell'IDE IntelliJ (consigliato).

Per avviare il programma selezionare Open-Weather_Project nel proprio package explorer e dare il comando Run 'OWPSpringBootApplication'.

All'avvio del programma seguire le indicazioni fornite dal menù da terminale.

STRUMENTI UTILIZZATI (SOFTWARE E LIBRERIE)

• IDE IntelliJ per creare il progetto assegnato;
• PostMan per testare e infine richiamare le API utilizzate (Current OpenWeather);
• Editor Markdown Monster per scrivere il README.md;
• Git e GitHub per il versioning del codice;
• Framework Spring, ed in particolare Spring Boot, per velocizzare lo sviluppo del progetto;
• Framework JUnit 5 per testare il funzionamento delle varie componenti del progetto;
• JavaDoc, per generare automaticamente la documentazione del codice sorgente scritto in Java;
• libreria org.json per "parsare" e generare Json file;
• libreria Apache Maven per la gestione delle dipendenze;

POSSIBILI APPLICAZIONI

I possibili clienti che possono usufruire di quest'applicazione sono tutti quei privati/aziende il cui lavoro è direttamente o indirettamente legato alle condizioni meteo, in particolare alla temperatura.

Alcuni esempi possono essere le imprese agricole, i settori legati al turismo (...impianti sciistici...), e infine settori legati ai cambiamenti climatici (...innalzamento del livello del mare...).

AUTORI E CONTRIBUTI

• Piercecchi Gabriel (50%): implementazione packages service, menu, controller e parzialmente utilities (classe ParseJSONDocument) e model (classe City);
• Rossi Alan (50%): implementazione packages stats, filters e le restanti classi in utilities e model (classe JSONStructure).