From 40e58cde9c16de14610181b8b090e0b4bba14ce8 Mon Sep 17 00:00:00 2001 From: L3o15 Date: Thu, 29 May 2025 10:39:51 +0000 Subject: [PATCH] JavaDoc --- .../arnaldo/rovineperdute/Coordinata.java | 30 ++++++++++++++++- src/it/unibs/arnaldo/rovineperdute/Graph.java | 33 ++++++++++++++++--- .../unibs/arnaldo/rovineperdute/Parser.java | 24 ++++++++++++++ .../arnaldo/rovineperdute/RovinaPerduta.java | 21 ++++++++++++ .../rovineperdute/RovinaPerdutaGrafo.java | 15 +++++++++ 5 files changed, 118 insertions(+), 5 deletions(-) diff --git a/src/it/unibs/arnaldo/rovineperdute/Coordinata.java b/src/it/unibs/arnaldo/rovineperdute/Coordinata.java index f739dae..72979d6 100644 --- a/src/it/unibs/arnaldo/rovineperdute/Coordinata.java +++ b/src/it/unibs/arnaldo/rovineperdute/Coordinata.java @@ -1,28 +1,51 @@ package it.unibs.arnaldo.rovineperdute; +/** + * Classe che rappresenta una coordinata nello spazio tridimensionale. + * Contiene le coordinate x, y e l'altezza. + */ public class Coordinata { private final int x; private final int y; private final int altezza; + /** + * Costruttore della classe Coordinata. + * @param x la coordinata x + * @param y la coordinata y + * @param altezza l'altezza della coordinata + */ public Coordinata(int x, int y, int altezza){ this.altezza = altezza; this.x = x; this.y = y; } + /** + * Getter per la coordinata x + * @return la coordinata x + */ public int getX() { return x; } + /** + * Getter per la coordinata y + * @return la coordinata y + */ public int getY() { return y; } + /** + * Getter per l'altezza della coordinata + * @return l'altezza della coordinata + */ public int getAltezza() { return altezza; } + @Override public String toString() { return "Coordinata{" + @@ -32,7 +55,12 @@ public class Coordinata { '}'; } - + /** + * Calcola la distanza tra questa coordinata e un'altra coordinata in base al tipo di veicolo. + * @param c la coordinata da confrontare + * @param tipoVeicolo il tipo di veicolo utilizzato per calcolare la distanza + * @return la distanza calcolata, o -1 se il tipo di veicolo non è riconosciuto + */ public double calcolaDistanza(Coordinata c, TipoVeicolo tipoVeicolo){ if (tipoVeicolo == TipoVeicolo.METZTLI){ return Math.abs(altezza - c.getAltezza()); diff --git a/src/it/unibs/arnaldo/rovineperdute/Graph.java b/src/it/unibs/arnaldo/rovineperdute/Graph.java index 3adca10..1286eb8 100644 --- a/src/it/unibs/arnaldo/rovineperdute/Graph.java +++ b/src/it/unibs/arnaldo/rovineperdute/Graph.java @@ -2,24 +2,42 @@ package it.unibs.arnaldo.rovineperdute; import java.util.*; +/** + * Classe che rappresenta un grafo di rovine perdute. + * Contiene metodi per aggiungere rovine, calcolare lo spanning tree e ottenere collegamenti tra rovine. + */ + public class Graph { private final HashMap> graph; + /** + * Costruttore della classe Graph. + * Inizializza un grafo vuoto. + */ public Graph(){ graph = new HashMap<>(); } - - public Graph(HashMap> graph){ - this.graph = graph; - } + /** + * Aggiunge una rovina perduta al grafo con i suoi collegamenti. + * @param rp la rovina perduta da aggiungere + * @param links la lista di rovine perdute collegate a rp + */ public void add(RovinaPerduta rp, List links) { graph.put(rp, links); } + /** + * Getter per ottenere il grafo delle rovine perdute. + * @return una mappa che associa ogni rovina perduta a una lista di rovine perdute collegate + */ public HashMap> getGraph() { return graph; } + /** + * Getters per ottenere la lista di rovine perdute collegate a una rovina specifica. + * @param rp la rovina perduta di cui si vogliono ottenere i collegamenti + */ public List getListaCollegamenti(RovinaPerduta rp){ return graph.get(rp); } @@ -37,6 +55,13 @@ public class Graph { return ret.toString(); } + /** + * Calcola lo spanning tree del grafo a partire da un punto di partenza specificato. + * Utilizza l'algoritmo di Dijkstra per trovare il percorso minimo verso la rovina perduta. + * @param puntoPartenza il punto di partenza da cui calcolare lo spanning tree + * @param tipo il tipo di veicolo utilizzato per calcolare le distanze + * @return una lista di RovinaPerdutaGrafo che rappresenta lo spanning tree + */ public List calcolaSpanningTree(RovinaPerduta puntoPartenza, TipoVeicolo tipo){ HashMap distanze = new HashMap<>(); HashMap predecessori = new HashMap<>(); diff --git a/src/it/unibs/arnaldo/rovineperdute/Parser.java b/src/it/unibs/arnaldo/rovineperdute/Parser.java index 30cba71..33c032e 100644 --- a/src/it/unibs/arnaldo/rovineperdute/Parser.java +++ b/src/it/unibs/arnaldo/rovineperdute/Parser.java @@ -8,8 +8,21 @@ import java.util.ArrayList; import java.util.HashMap; import java.util.List; +/** + * Classe che gestisce il parsing del file XML delle rovine perdute e la generazione di un file XML con le rotte. + * Contiene metodi per leggere il file XML, costruire il grafo delle rovine e generare un file XML con le rotte. + */ public class Parser { + /** + * Metodo per leggere un file XML contenente le rovine perdute e costruire un grafo. + * Il file XML deve seguire una struttura specifica in cui ogni rovina è rappresentata da un elemento "city" + * e i collegamenti tra le rovine sono rappresentati da elementi "link". + * + * @param fileName il nome del file XML da leggere + * @return un oggetto Graph che rappresenta il grafo delle rovine perdute + */ + // rovina = città public static Graph parseRovinePerduteXML(String fileName) { @@ -81,9 +94,13 @@ public class Parser { } xmlr.close(); + + // creo il grafo Graph grafo = new Graph(); + // aggiungo le rovine al grafo for (Integer idx : mappaCollegamenti.keySet()){ + // trasformo gli indici dei collegamenti in RovinaPerduta List listaIndiciCollegamenti = mappaCollegamenti.get(idx); List listaCollegamenti = new ArrayList<>(); RovinaPerduta rp = rovineMap.get(idx); @@ -103,6 +120,13 @@ public class Parser { } } + /** + * Metodo per generare un file XML contenente le rotte delle due squadre Tonatiuh e Metztli. + * Il file XML conterrà le informazioni sulle città visitate, il costo totale e il numero di città per ogni squadra. + * + * @param minimumTreeTonatium la lista delle rovine per la squadra Tonatiuh + * @param minimumTreeMetztli la lista delle rovine per la squadra Metztli + */ public static void generaXML(List minimumTreeTonatium, List minimumTreeMetztli) { String fileName = "routes.xml"; diff --git a/src/it/unibs/arnaldo/rovineperdute/RovinaPerduta.java b/src/it/unibs/arnaldo/rovineperdute/RovinaPerduta.java index 51188d7..a317d22 100644 --- a/src/it/unibs/arnaldo/rovineperdute/RovinaPerduta.java +++ b/src/it/unibs/arnaldo/rovineperdute/RovinaPerduta.java @@ -1,24 +1,45 @@ package it.unibs.arnaldo.rovineperdute; +/** + * Classe che rappresenta una città perduta, ovvero una rovina con le sue coordinate, nome e ID. + */ public class RovinaPerduta { private final Coordinata coordinata; private final String nome; private final int id; + /** + * Costruttore della classe RovinaPerduta. + * @param coordinata la coordinata della rovina perduta + * @param nome il nome della rovina perduta + * @param id l'ID della rovina perduta + */ public RovinaPerduta(Coordinata coordinata, String nome, int id) { this.coordinata = coordinata; this.nome = nome; this.id = id; } + /** + * Getter per le coordinate della rovina perduta. + * @return la coordinata della rovina perduta + */ public Coordinata getCoordinata() { return coordinata; } + /** + * Getter per il nome della rovina perduta. + * @return il nome della rovina perduta + */ public String getNome() { return nome; } + /** + * Getter per l'ID della rovina perduta. + * @return l'ID della rovina perduta + */ public int getId(){ return id; } diff --git a/src/it/unibs/arnaldo/rovineperdute/RovinaPerdutaGrafo.java b/src/it/unibs/arnaldo/rovineperdute/RovinaPerdutaGrafo.java index 92bb026..2af3ba9 100644 --- a/src/it/unibs/arnaldo/rovineperdute/RovinaPerdutaGrafo.java +++ b/src/it/unibs/arnaldo/rovineperdute/RovinaPerdutaGrafo.java @@ -1,13 +1,28 @@ package it.unibs.arnaldo.rovineperdute; +/** + * Classe che estende RovinaPerduta per rappresentare una rovina perduta con una distanza specifica. + * Questa classe è utilizzata per gestire le rovine perdute in un grafo, dove la distanza rappresenta + */ public class RovinaPerdutaGrafo extends RovinaPerduta{ private final double distanza; + /** + * Costruttore della classe RovinaPerdutaGrafo. + * @param coordinata la coordinata della rovina perduta + * @param nome il nome della rovina perduta + * @param id l'ID della rovina perduta + * @param distanza la distanza dalla rovina perduta + */ public RovinaPerdutaGrafo(Coordinata coordinata, String nome, int id, double distanza) { super(coordinata, nome, id); this.distanza = distanza; } + /** + * Getter per la distanza della rovina perduta. + * @return la distanza dalla rovina perduta + */ public double getDistanza() { return distanza; }