From d3a65e87de26117b1b41712f37b2d21891496cdc Mon Sep 17 00:00:00 2001 From: Nathanael Jourdane Date: Tue, 15 Mar 2016 15:24:50 +0100 Subject: [PATCH] Improve Javadoc. --- src/main/java/eu/omp/irap/vespa/epntapclient/view/ParamField.java | 8 ++++---- src/main/java/eu/omp/irap/vespa/epntapclient/votable/Utils.java | 23 +++++++++++++++++++++-- src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableController.java | 21 +++++++++++---------- src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableException.java | 103 +++++++++++++++++++++++++------------------------------------------------------------------------------ src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableParser.java | 20 ++++++++++---------- src/main/java/eu/omp/irap/vespa/epntapclient/votable/view/VOTableView.java | 2 +- 6 files changed, 72 insertions(+), 105 deletions(-) diff --git a/src/main/java/eu/omp/irap/vespa/epntapclient/view/ParamField.java b/src/main/java/eu/omp/irap/vespa/epntapclient/view/ParamField.java index b378fa3..e6e4b8e 100644 --- a/src/main/java/eu/omp/irap/vespa/epntapclient/view/ParamField.java +++ b/src/main/java/eu/omp/irap/vespa/epntapclient/view/ParamField.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); diff --git a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/Utils.java b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/Utils.java index 798f9f6..3ad8fe1 100644 --- a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/Utils.java +++ b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/Utils.java @@ -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 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. diff --git a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableController.java b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableController.java index d19f79d..d0503c4 100644 --- a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableController.java +++ b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableController.java @@ -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); } } diff --git a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableException.java b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableException.java index 53b45fe..cf8901c 100644 --- a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableException.java +++ b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableException.java @@ -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 diff --git a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableParser.java b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableParser.java index 266c2ce..3ebcd6b 100644 --- a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableParser.java +++ b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/controller/VOTableParser.java @@ -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); diff --git a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/view/VOTableView.java b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/view/VOTableView.java index 65a775c..9ad0b31 100644 --- a/src/main/java/eu/omp/irap/vespa/epntapclient/votable/view/VOTableView.java +++ b/src/main/java/eu/omp/irap/vespa/epntapclient/votable/view/VOTableView.java @@ -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; -- libgit2 0.21.2