Add Javadoc.

Nathanael Jourdane
1 parent 987f00a7
Showing 13 changed files with 129 additions and 32 deletions Show diff stats
src/main/java/eu/omp/irap/vespa/epntapclient/EpnTapException.java
src/main/java/eu/omp/irap/vespa/epntapclient/RequestCtrl.java
src/main/java/eu/omp/irap/vespa/epntapclient/ServicesList.java
src/main/java/eu/omp/irap/vespa/epntapclient/granule/Granule.java
src/main/java/eu/omp/irap/vespa/epntapclient/gui/mainpanel/MainPanelCtrl.java
src/main/java/eu/omp/irap/vespa/epntapclient/gui/mainpanel/MainPanelListener.java
src/main/java/eu/omp/irap/vespa/epntapclient/gui/resultpanel/ResultPanelCtrl.java
src/main/java/eu/omp/irap/vespa/epntapclient/gui/resultpanel/ResultPanelListener.java
src/main/java/eu/omp/irap/vespa/epntapclient/gui/servicespanel/ServicesPanelCtrl.java
src/main/java/eu/omp/irap/vespa/epntapclient/gui/servicespanel/ServicesPanelListener.java
src/main/java/eu/omp/irap/vespa/epntapclient/gui/servicespanel/ServicesPanelView.java
src/test/java/eu/omp/irap/vespa/epntapclient/granule/GranuleCtrlTest.java
src/test/java/eu/omp/irap/vespa/epntapclient/granule/GranuleTest.java
@@ -34,6 +34,7 @@ public class EpnTapException extends Exception {
 	/**
 	 * @param message A message describing the error.
+	 * @param e The exception thrown.
 	 */
 	public EpnTapException(String message, Exception e) {
 		super(message, e);
@@ -57,7 +57,8 @@ public class RequestCtrl {
 	private Map<String, Object> parameters = new HashMap<>();
 	/**
-	 * The query to send, with the name of the table is replaced by {@link #KEYWORD_TABLE_NAME}.
+	 * The query to send, containing {@link #KEYWORD_TABLE_NAME} which will be replaced by the
+	 * actual name of each table.
 	 */
 	private String query;
@@ -75,6 +76,7 @@ public class RequestCtrl {
 	 * Constructor of RequestCtrl.
 	 *
 	 * @param nbMaxResult The maximum number of rows returned by the query.
+	 * @param columnNames The names of the columns used in the SELECT keyword in the query.
 	 */
 	public RequestCtrl(int nbMaxResult, List<String> columnNames) {
 		this.nbMaxResult = nbMaxResult;
@@ -104,6 +106,9 @@ public class RequestCtrl {
 		return targetNames;
 	}
+	/**
+	 * @return The names of the columns used in the SELECT keyword in the query.
+	 */
 	public List<String> getColumnNames() {
 		return columnNames;
 	}
@@ -124,10 +129,20 @@ public class RequestCtrl {
 		return parameters;
 	}
+	/**
+	 * @return The query to send, with the name of the table is replaced by
+	 *         {@link #KEYWORD_TABLE_NAME}.
+	 */
 	public String getQuery() {
 		return query;
 	}
+	/**
+	 * Get the query and replace the {@link #KEYWORD_TABLE_NAME} by the specified tableName.
+	 *
+	 * @param tableName The name of the table, to put in the FROM ADQL keyword.
+	 * @return The ADQL query, containing the specified table name.
+	 */
 	public String getQuery(String tableName) {
 		return query.replace(KEYWORD_TABLE_NAME, tableName);
 	}
@@ -142,6 +157,11 @@ public class RequestCtrl {
 		LOGGER.info("removed " + paramName);
 	}
+	/**
+	 * Set the names of the columns used in the SELECT keyword in the query.
+	 *
+	 * @param columnNames The columns names.
+	 */
 	public void setColumnNames(List<String> columnNames) {
 		this.columnNames = columnNames;
 	}
@@ -155,6 +175,11 @@ public class RequestCtrl {
 		nbMaxResult = nbRows;
 	}
+	/**
+	 * Set the query, containing {@link #KEYWORD_TABLE_NAME}.
+	 * 
+	 * @param query The query.
+	 */
 	public void setQuery(String query) {
 		this.query = query;
 	}
@@ -30,12 +30,16 @@ public class ServicesList {
 	/** The logger for the class ServicesList. */
 	private static final Logger LOGGER = Logger.getLogger(ServicesList.class.getName());
+	/** The list of table names entered in the custom table name field. */
 	private List<String> customTableNames;
+	/** The list of target URLs entered in the custom target URL field. */
 	private List<String> customTargetUrls;
+	/** The list of table names selected in the services table. */
 	private List<String> selectedTableNames;
+	/** The list of target URLs selected in the services table. */
 	private List<String> selectedTargetUrls;
@@ -69,6 +73,12 @@ public class ServicesList {
 		return targetUrls;
 	}
+	/**
+	 * Update the services (table name and target URLs) entered in the custom services fields.
+	 *
+	 * @param customTableNamesToAdd The list of the table names to update.
+	 * @param customTargetUrlsToAdd The list of the target URLs to update.
+	 */
 	public void updateCustomServices(List<String> customTableNamesToAdd,
 			List<String> customTargetUrlsToAdd) {
 		customTableNames = customTableNamesToAdd;
@@ -77,6 +87,12 @@ public class ServicesList {
 		LOGGER.info("Updated custom services URLs: " + StringJoiner.join(customTargetUrls));
 	}
+	/**
+	 * Update the services (table name and target URLs) selected in the services table.
+	 *
+	 * @param selectedTableNamesToAdd The list of the table names to update.
+	 * @param selectedTargetUrlsToAdd The list of the target URLs to update.
+	 */
 	public void updateSelectedServices(List<String> selectedTableNamesToAdd,
 			List<String> selectedTargetUrlsToAdd) {
 		selectedTableNames = selectedTableNamesToAdd;
@@ -291,6 +291,11 @@ public class Granule {
 		this.granuleUid = granuleUid;
 	}
+	/**
+	 * Convert the Granule to a Map, as <Granule name, Granule value>.
+	 *
+	 * @return the Granule as a map.
+	 */
 	public Map<String, Object> asMap() {
 		Map<String, Object> map = new HashMap<>();
 		map.put(GranuleEnum.GRANULE_UID.toString(), granuleUid);
@@ -948,6 +953,10 @@ public class Granule {
 		return true;
 	}
+	/**
+	 * @return a string containing all the parameters of the Granule, as strings (key: value). Used
+	 *         to be printed for debug purposes.
+	 */
 	public String printAll() {
 		String s = "";
 		for (Map.Entry<String, Object> parameter : asMap().entrySet()) {
@@ -16,7 +16,6 @@
 package eu.omp.irap.vespa.epntapclient.gui.mainpanel;
-import java.util.List;
 import java.util.logging.Level;
 import java.util.logging.Logger;
@@ -89,11 +88,6 @@ public class MainPanelCtrl extends EpnTapController implements MainPanelListener
 		return servicesPanelCtrl;
 	}
-	@Override
-	public List<String> getTableNames() {
-		return servicesPanelCtrl.getServices().getTableNames();
-	}
-
 	/**
 	 * @return The main view of the application.
 	 */
@@ -16,18 +16,26 @@
 package eu.omp.irap.vespa.epntapclient.gui.mainpanel;
-import java.util.List;
-
 /**
  * @author N. Jourdane
  */
 public interface MainPanelListener {
+	/**
+	 * Ask the main panel to open a pop-up and display the specified error.
+	 *
+	 * @param message A short message describing the error, which will be the pop-up title.
+	 * @param e The error itself.
+	 */
 	void displayError(String message, Exception e);
-	List<String> getTableNames();
-
+	/**
+	 * Ask the main panel to send the query.
+	 */
 	void sendQuery();
+	/**
+	 * Ask the main panel to update the query.
+	 */
 	void updateQuery();
 }
@@ -44,6 +44,8 @@ public class ResultPanelCtrl extends VOTableController implements ResultPanelLis
 	/**
 	 * Constructor of ResultPanelCtrl.
+	 * 
+	 * @param listener The listener of the main panel.
 	 */
 	public ResultPanelCtrl(MainPanelListener listener) {
 		this.listener = listener;
@@ -18,7 +18,6 @@ package eu.omp.irap.vespa.epntapclient.gui.resultpanel;
 import java.io.File;
-import eu.omp.irap.vespa.votable.controller.VOTableException.CantSaveVOTableException;
 import eu.omp.irap.vespa.votable.view.VOTableViewListener;
 /**
@@ -31,7 +30,6 @@ public interface ResultPanelListener extends VOTableViewListener {
 	 *
 	 * @param file The file selected by the user in the FileChooser pop-up, corresponding to the
 	 *            place where save the VOTable.
-	 * @throws CantSaveVOTableException The VOTable can not be saved at the specified location.
 	 */
 	public void onDownloadButtonClicked(File file);
 }
@@ -93,7 +93,7 @@ public class ServicesPanelCtrl extends VOTableController implements ServicesPane
 	}
 	@Override
-	public void onServiceUpdated() {
+	public void onServiceListUpdated() {
 		String tableName = view.getTableNameTextField().getText();
 		String targetUrl = view.getServiceUrlTextField().getText();
 		List<String> customTableNames = Arrays.asList(tableName.split(CUSTOM_SERVICES_SEPARATOR));
@@ -23,5 +23,8 @@ import eu.omp.irap.vespa.votable.view.VOTableViewListener;
  */
 public interface ServicesPanelListener extends VOTableViewListener {
-	public void onServiceUpdated();
+	/**
+	 * This method is called when the services list is updated.
+	 */
+	public void onServiceListUpdated();
 }
@@ -56,22 +56,27 @@ public class ServicesPanelView extends VOTableView {
 		buildServicesPanel();
 	}
+	/**
+	 * Add to a textField a listener to listen for text update events (changed, inserted, removed).
+	 *
+	 * @param textField the textField to listen.
+	 */
 	public void addEventListener(JTextField textField) {
 		textField.getDocument().addDocumentListener(new DocumentListener() {
 			@Override
 			public void changedUpdate(DocumentEvent e) {
-				listener.onServiceUpdated();
+				listener.onServiceListUpdated();
 			}
 			@Override
 			public void insertUpdate(DocumentEvent e) {
-				listener.onServiceUpdated();
+				listener.onServiceListUpdated();
 			}
 			@Override
 			public void removeUpdate(DocumentEvent e) {
-				listener.onServiceUpdated();
+				listener.onServiceListUpdated();
 			}
 		});
 	}
@@ -32,28 +32,23 @@ import eu.omp.irap.vespa.votable.votabledata.VoTableDataTest;
  */
 public class GranuleCtrlTest {
+	/** The granule controller, initialized with {@link VoTableDataTest#createVoTableData()}. */
 	GranuleCtrl granuleCtrl;
+	/**
+	 * Constructor of GranuleCtrlTest.
+	 */
 	public GranuleCtrlTest() {
 		granuleCtrl = new GranuleCtrl(VoTableDataTest.createVoTableData());
 	}
+	/**
+	 * Test the method {@link GranuleCtrl#getGranuleFromVOTableRow(int)} by comparing the granules
+	 * with voTableData.
+	 */
 	@Test
-	public void getGranulesTest() {
-		List<Granule> granules = null;
-		try {
-			granules = granuleCtrl.getGranules();
-		} catch (CanNotParseDataException e) {
-			fail("Can not parse granule: " + e.getMessage());
-		}
-		assertNotNull(granules);
-		assertTrue(granules.get(0).equals(GranuleTest.createGranule1()));
-		assertTrue(granules.get(1).equals(GranuleTest.createGranule2()));
-	}
-
-	@Test
-	public void parseStringTest() {
+	public void getGranuleFromVOTableRowTest() {
 		Granule g1 = null;
 		Granule g2 = null;
 		try {
@@ -67,4 +62,20 @@ public class GranuleCtrlTest {
 		assertTrue(g1.equals(GranuleTest.createGranule1()));
 		assertTrue(g2.equals(GranuleTest.createGranule2()));
 	}
+
+	/**
+	 * Test the method {@link GranuleCtrl#getGranules()} by comparing the granules with voTableData.
+	 */
+	@Test
+	public void getGranulesTest() {
+		List<Granule> granules = null;
+		try {
+			granules = granuleCtrl.getGranules();
+		} catch (CanNotParseDataException e) {
+			fail("Can not parse granule: " + e.getMessage());
+		}
+		assertNotNull(granules);
+		assertTrue(granules.get(0).equals(GranuleTest.createGranule1()));
+		assertTrue(granules.get(1).equals(GranuleTest.createGranule2()));
+	}
 }
@@ -27,6 +27,8 @@ import java.util.logging.Logger;
 import org.junit.Test;
+import eu.omp.irap.vespa.votable.votabledata.VoTableDataTest;
+
 /**
  * @author N. Jourdane
  */
@@ -36,6 +38,12 @@ public class GranuleTest {
 	private static final Logger LOGGER = Logger.getLogger(GranuleTest.class.getName());
+	/**
+	 * Create a granule for tests purposes. It is planetary data for Uranus, got from an actual ADQL
+	 * query, exactly the same content that {@link VoTableDataTest#createDataArray1()}
+	 *
+	 * @return The granule.
+	 */
 	public static Granule createGranule1() {
 		Date testDate = null;
 		try {
@@ -91,6 +99,12 @@ public class GranuleTest {
 		return completeGranule;
 	}
+	/**
+	 * Create a granule for tests purposes. It is planetary data for Neptune, got from an actual
+	 * query, exactly the same content that {@link VoTableDataTest#createDataArray2()}
+	 *
+	 * @return The granule.
+	 */
 	public static Granule createGranule2() {
 		Date testDate = null;
 		try {
@@ -146,18 +160,29 @@ public class GranuleTest {
 		return completeGranule;
 	}
+	/**
+	 * Create an incomplete granule without many mandatory parameters, which is forbidden.
+	 *
+	 * @return the granule.
+	 */
 	public static Granule createIncompleteGranule() {
 		Granule incompleteGranule = new Granule("Mercury");
 		incompleteGranule.setGranuleGid("Planet");
 		return incompleteGranule;
 	}
+	/**
+	 * Test if the incomplete granule appears like not valid.
+	 */
 	@SuppressWarnings("static-method") // Otherwise JUnit doesn't work.
 	@Test
 	public void isNotValidTest() {
 		assertFalse("The incomplete granule is valid.", createIncompleteGranule().isValid());
 	}
+	/**
+	 * Test if a complete granule appears like valid.
+	 */
 	@SuppressWarnings("static-method") // Otherwise JUnit doesn't work.
 	@Test
 	public void isValidTest() {