Improve Javadoc.

Nathanael Jourdane
1 parent 4164c074
Showing 6 changed files with 72 additions and 105 deletions Show diff stats
src/main/java/eu/omp/irap/vespa/epntapclient/view/ParamField.java
src/main/java/eu/omp/irap/vespa/epntapclient/votable/Utils.java
src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableController.java
src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableException.java
src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableParser.java
src/main/java/eu/omp/irap/vespa/epntapclient/votable/view/VOTableView.java
@@ -43,7 +43,7 @@ import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
 import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableConnection;
-import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.SendQueryException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantSendQueryException;
 /**
  * A field used to set a service parameter to build the query (in the parameter panel). ParamField
@@ -353,9 +353,9 @@ public abstract class ParamField extends JPanel {
 		 * 
 		 * @param begining The beginning of the target_name.
 		 * @return An array of Strings corresponding to the target names got.
-		 * @throws SendQueryException If the resolver do not work.
+		 * @throws CantSendQueryException If the resolver do not work.
 		 */
-		static String[] getItems(String begining) throws SendQueryException {
+		static String[] getItems(String begining) throws CantSendQueryException {
 			StringBuilder resolverResult = null;
 			resolverResult = VOTableConnection.sendGet(RESOLVER_URL, "q=\"" + begining + "\"");
 			JsonObject root = new JsonParser().parse(resolverResult.toString()).getAsJsonObject();
@@ -386,7 +386,7 @@ public abstract class ParamField extends JPanel {
 							for (String s : getItems(content)) {
 								comboBox.addItem(s);
 							}
-						} catch (SendQueryException e) {
+						} catch (CantSendQueryException e) {
 							logger.log(Level.WARNING, "Can't get table names for the resolver", e);
 						}
 						comboBox.getEditor().setItem(content);
@@ -34,17 +34,36 @@ public class Utils {
 	/** The logger for the class Utils. */
 	private static final Logger logger = Logger.getLogger(Utils.class.getName());
+	/**
+	 * StringJoiner has the same purpose of Java 8 StringJoiner, it has been rewritten for Java7
+	 * compatibility.
+	 * 
+	 * @author N. Jourdane
+	 */
 	public static class StringJoiner {
-		String separator;
+		/** A list of words to join, ie. ["foo", "bar"]. */
 		List<String> list;
+		/** The string joiner separator to put between each word, ie. ';'. */
+		String separator;
+		/** The resulting string, ie. "foo;bar". */
 		String string;
+		/**
+		 * Method constructor for the String joiner.
+		 * 
+		 * @param separator The string joiner separator to put between each word, ie. ';'.
+		 */
 		public StringJoiner(String separator) {
 			this.separator = separator;
 			this.list = new ArrayList<>();
 			string = "";
 		}
+		/**
+		 * add a new word to the joiner.
+		 * 
+		 * @param text The word to add.
+		 */
 		public void add(String text) {
 			if ("".equals(string)) {
 				string = text;
@@ -60,7 +79,7 @@ public class Utils {
 	}
 	/**
-	 * Print the specified object in JSON format in a file on the temp directory.
+	 * Print the specified object in JSON format in a file on the temporary directory.
 	 * 
 	 * @param title The name of the file.
 	 * @param obj the object to print in a file.
@@ -19,11 +19,11 @@ package eu.omp.irap.vespa.epntapclient.votable.controller;
 import java.io.IOException;
 import java.util.logging.Logger;
-import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantFillTableException;
-import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantFillTableException.CantModifyVOTableException;
-import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantFillTableException.ErrorMessageInVOTableException;
-import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantFillTableException.SeveralResourcesException;
-import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantFillTableException.SeveralTablesException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException.CantModifyVOTableException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException.ErrorMessageInVOTableException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException.SeveralResourcesException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException.SeveralTablesException;
 import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantSendQueryException;
 import eu.omp.irap.vespa.epntapclient.votable.model.Table;
 import eu.omp.irap.vespa.epntapclient.votable.model.VOTABLE;
@@ -82,20 +82,21 @@ public class VOTableController {
 	 * @param queryLanguage The language used for the queries (ie. "ADQL").
 	 * @param query The query to ask to the registry.
 	 * @throws CantSendQueryException If the query can not be sent.
-	 * @throws CantFillTableException If the table can not be filled. @see CantFillTableException
+	 * @throws CantDisplayVOTableException If the table can not be filled. @see
+	 *             CantFillTableException
 	 */
 	public void fillTable(String targetURL, String queryLanguage, String query)
-			throws CantFillTableException, CantSendQueryException {
+			throws CantDisplayVOTableException, CantSendQueryException {
 		String voTablePath = VOTableConnection.sendQuery(targetURL, queryLanguage, query);
 		fillTable(voTablePath);
 	}
 	/**
 	 * @param voTablePath The path of the VOTable file.
-	 * @throws CantFillTableException If the VOTable can not be filled.
+	 * @throws CantDisplayVOTableException If the VOTable can not be filled.
 	 */
 	public void fillTable(String voTablePath)
-			throws CantFillTableException {
+			throws CantDisplayVOTableException {
 		voTable = VOTableParser.parseVOTable(voTablePath);
@@ -121,7 +122,7 @@ public class VOTableController {
 			dataParser = new VOTableDataParser(table);
 			view.fillTable(dataParser.getColumnsName(), dataParser.getDataArray());
 		} catch (IOException e) {
-			throw new CantModifyVOTableException(e);
+			throw new CantModifyVOTableException(voTablePath, e);
 		}
 	}
@@ -30,8 +30,6 @@ public abstract class VOTableException extends Exception {
 	private static final long serialVersionUID = -5707662871529583209L;
 	/**
-	 * Method constructor
-	 * 
 	 * @param message The message describing the exception displayed in the error dialog.
 	 */
 	public VOTableException(String message) {
@@ -39,8 +37,6 @@ public abstract class VOTableException extends Exception {
 	}
 	/**
-	 * Method constructor
-	 * 
 	 * @param message The message describing the exception displayed in the error dialog.
 	 * @param e The exception thrown.
 	 */
@@ -48,16 +44,10 @@ public abstract class VOTableException extends Exception {
 		super(message, e);
 	}
-	/**
-	 * Abstract exception for when the application can not send the query.
-	 * 
-	 * @author N. Jourdane
-	 */
+	/** Abstract exception for when the application can not send the query. */
 	public abstract static class CantSendQueryException extends VOTableException {
 		/**
-		 * Method constructor with a message.
-		 * 
 		 * @param message The message describing the exception displayed in the error dialog.
 		 */
 		public CantSendQueryException(String message) {
@@ -65,8 +55,6 @@ public abstract class VOTableException extends Exception {
 		}
 		/**
-		 * Method constructor with a message and and exception.
-		 * 
 		 * @param message The message describing the exception displayed in the error dialog.
 		 * @param e The exception thrown.
 		 */
@@ -74,13 +62,10 @@ public abstract class VOTableException extends Exception {
 			super(message, e);
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** The URL is not correctly formated. */
 		public static class MalformedURLException extends CantSendQueryException {
+
 			/**
-			 * Method constructor
-			 * 
 			 * @param uri The URI sent to the server.
 			 * @param e The exception thrown.
 			 */
@@ -89,13 +74,10 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** Can not print the result in the file. */
 		public static class CantPrintRequestResultException extends CantSendQueryException {
+
 			/**
-			 * Method constructor
-			 * 
 			 * @param resultFilePath The path of the file where the query results should be stored.
 			 * @param e The exception thrown.
 			 */
@@ -104,13 +86,10 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** Can not open an HTTP connection to the specified URL. */
 		public static class CantOpenConnectionException extends CantSendQueryException {
+
 			/**
-			 * Method constructor
-			 * 
 			 * @param uri The URI sent to the server.
 			 * @param e The exception thrown.
 			 */
@@ -119,13 +98,10 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** Can not get the server response code for the request. */
 		public static class CantGetResponseCode extends CantSendQueryException {
+
 			/**
-			 * Method constructor
-			 * 
 			 * @param uri The URI sent to the server.
 			 * @param e The exception thrown.
 			 */
@@ -134,13 +110,10 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** The server returned the bad response code (but not 400). */
 		public static class BadResponseCodeException extends CantSendQueryException {
+
 			/**
-			 * Method constructor
-			 * 
 			 * @param uri The URI sent to the server.
 			 * @param responseCode The HTTP GET response code, which is bad.
 			 */
@@ -150,13 +123,10 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** Can not get the input stream of the result, neither the error stream. */
 		public static class CantGetErrorStream extends CantSendQueryException {
+
 			/**
-			 * Method constructor
-			 * 
 			 * @param uri The URI sent to the server.
 			 * @param e The exception thrown.
 			 */
@@ -168,14 +138,10 @@ public abstract class VOTableException extends Exception {
 	}
-	/**
-	 * @author N. Jourdane
-	 */
+	/** Abstract exception for when the application can not display the VOTable. */
 	public abstract static class CantDisplayVOTableException extends VOTableException {
 		/**
-		 * Method constructor
-		 * 
 		 * @param message The message describing the exception displayed in the error dialog.
 		 * @param e The exception thrown.
 		 */
@@ -184,22 +150,17 @@ public abstract class VOTableException extends Exception {
 		}
 		/**
-		 * Method constructor
-		 * 
 		 * @param message The message describing the exception displayed in the error dialog.
 		 */
 		public CantDisplayVOTableException(String message) {
 			super(message);
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** Can not parse the VOTable because it doesn't match with the VOTable schema. */
 		public static class VOTableIsNotValidException extends CantDisplayVOTableException {
 			/**
-			 * Method constructor
-			 * 
+			 * @param voTablePath The path of the VOTable.
 			 * @param e The exception thrown.
 			 */
 			public VOTableIsNotValidException(String voTablePath, Exception e) {
@@ -208,15 +169,11 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** VOTable with more than one resource are not yet supported. */
 		public static class SeveralResourcesException extends CantDisplayVOTableException {
 			/**
-			 * Method constructor
-			 * 
-			 * @param voTablePath
+			 * @param voTablePath The path of the VOTable.
 			 */
 			public SeveralResourcesException(String voTablePath) {
 				super("VOTable with more than one resource are not yet supported. \n"
@@ -224,15 +181,11 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** VOTable with more than one resource are not yet supported. */
 		public static class SeveralTablesException extends CantDisplayVOTableException {
 			/**
-			 * Method constructor
-			 * 
-			 * @param voTablePath
+			 * @param voTablePath The path of the VOTable.
 			 */
 			public SeveralTablesException(String voTablePath) {
 				super("VOTable with more than one resource are not yet supported. \n"
@@ -240,13 +193,10 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** Can not change schema location on the VOTable file. */
 		public static class CantModifyVOTableException extends CantDisplayVOTableException {
 			/**
-			 * Method constructor
-			 * 
+			 * @param voTablePath The path of the VOTable.
 			 * @param e The exception thrown.
 			 */
 			public CantModifyVOTableException(String voTablePath, Exception e) {
@@ -254,14 +204,11 @@ public abstract class VOTableException extends Exception {
 			}
 		}
-		/**
-		 * @author N. Jourdane
-		 */
+		/** There is an error in the VOTable. */
 		public static class ErrorMessageInVOTableException extends CantDisplayVOTableException {
 			/**
-			 * Method constructor
-			 * 
-			 * @param errorInfo
+			 * @param errorInfo The information about the error, which comes from the VOTable itself
+			 *            from the "INFO" node.
 			 */
 			public ErrorMessageInVOTableException(String errorInfo) {
 				super("There is an error in the VOTable:\n" + errorInfo
@@ -36,7 +36,9 @@ import org.w3c.dom.Document;
 import org.w3c.dom.NamedNodeMap;
 import org.xml.sax.SAXException;
-import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantFillTableException.VOTableParsingException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException.CantModifyVOTableException;
+import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.CantDisplayVOTableException.VOTableIsNotValidException;
 import eu.omp.irap.vespa.epntapclient.votable.model.VOTABLE;
 /**
@@ -65,24 +67,23 @@ public final class VOTableParser {
 	/**
 	 * @param voTablePath The path of the VOTable.
 	 * @return The VOTable resulting of the XML document.
-	 * @throws VOTableParsingException Can not parse the VOTable.
+	 * @throws CantDisplayVOTableException VOTable is not valid or not writable.
 	 */
-	public static VOTABLE parseVOTable(String voTablePath) throws VOTableParsingException {
+	public static VOTABLE parseVOTable(String voTablePath) throws CantDisplayVOTableException {
+		// TODO: Change the name of the 2nd INFO tag instead of editing the XSD file.
+		VOTABLE voTable;
+		JAXBContext jc;
 		try {
 			changeVOTableSchemaLocation(voTablePath);
 		} catch (IOException e) {
-			throw new VOTableParsingException("Can not change the VOTable schema location.", e);
+			throw new CantModifyVOTableException(voTablePath, e);
 		}
-
-		// TODO: Change the name of the 2nd INFO tag instead of editing the XSD file.
-		VOTABLE voTable;
-		JAXBContext jc;
 		try {
 			jc = JAXBContext.newInstance(VOTABLE_MODEL_PACKAGE);
 			Unmarshaller unmarshaller = jc.createUnmarshaller();
 			voTable = (VOTABLE) unmarshaller.unmarshal(new File(voTablePath));
 		} catch (JAXBException e) {
-			throw new VOTableParsingException("Can not change the VOTable schema location.", e);
+			throw new VOTableIsNotValidException(voTablePath, e);
 		}
 		return voTable;
@@ -114,7 +115,6 @@ public final class VOTableParser {
 				logger.info("VOTable version is " + version + ", everything is ok.");
 			}
-			// write the content into xml file
 			Transformer transformer = TransformerFactory.newInstance().newTransformer();
 			StreamResult result = new StreamResult(new File(voTablePath));
 			transformer.transform(new DOMSource(doc), result);
@@ -39,7 +39,7 @@ public class VOTableView extends JPanel implements TableModelListener {
 	/** The logger for the class VOTableView. */
 	static final Logger logger = Logger.getLogger(VOTableView.class.getName());
-	// TODO: Create classes VOTableGUI and VOTableCLI which implements an interface VOTableView
+	// TODO: Create class VOTableCLI the view for a CLI usage
 	/** The serial version UID (affected with a random number). */
 	private static final long serialVersionUID = -6131752938586134234L;