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 2f4b832..b378fa3 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 @@ -46,12 +46,15 @@ import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableConnection; import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.SendQueryException; /** - * A field used to set a service parameter to build the query (in the parameter panel). + * A field used to set a service parameter to build the query (in the parameter panel). ParamField + * is an abstract method and all type of parameter field should extend it. See + * https://voparis-confluence.obspm.fr/display/VES/4+-+EPN-TAP+queries to get all parameters + * details. * * @author N. Jourdane */ public abstract class ParamField extends JPanel { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = 6025994164004985362L; /** The logger for the class ParamField. */ @@ -82,6 +85,13 @@ public abstract class ParamField extends JPanel { /** The parameter name of the field */ protected String paramName; + /** + * Method constructor for the parameter field abstract class, which do all common action for all + * type of field, such as displaying the name of the parameter. + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public ParamField(EpnTapMainView mainView, String paramName) { super(); @@ -97,11 +107,24 @@ public abstract class ParamField extends JPanel { // TODO: Add tooltip text based on rr.table_column.column_description } + /** + * The string field is used for parameter with a `String` class. It is a simple JTextField with + * no verification. The parameter is sent to the controller each time it is modified. + * + * @author N. Jourdane + */ public static class StringField extends ParamField implements TextFieldListener { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = 24219488975302068L; + /** The JTextField used to put the parameter value. */ JTextField field; + /** + * Method constructor for the string field. + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public StringField(EpnTapMainView mainView, String paramName) { super(mainView, paramName); field = new JTextField(); @@ -109,6 +132,9 @@ public abstract class ParamField extends JPanel { this.add(field); } + /** + * This method is called each time the field is modified. + */ @Override public void update(JTextField textField) { if ("".equals(textField.getText())) { @@ -119,11 +145,25 @@ public abstract class ParamField extends JPanel { } } + /** + * The float field is used for parameter with a `Float` class. It is a JTextField which checks + * if the content is a valid float. If the parameter is valid or if it is empty, then the float + * value is sent to the controller. + * + * @author N. Jourdane + */ public static class FloatField extends ParamField implements TextFieldListener { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = -1880193152285564590L; + /** The JTextField used to put the parameter value. */ JTextField field; + /** + * Method constructor + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public FloatField(EpnTapMainView mainView, String paramName) { super(mainView, paramName); field = new JTextField(); @@ -131,6 +171,9 @@ public abstract class ParamField extends JPanel { this.add(field); } + /** + * This method is called each time the field is modified. + */ @Override public void update(JTextField textField) { if ("".equals(textField.getText())) { @@ -148,12 +191,28 @@ public abstract class ParamField extends JPanel { } } + /** + * The date range field is used for couples of parameter with both a `Date` type (actually only + * `time_min` and `time_max` parameters is concerned for now). These are JTextFields which check + * if the content is a valid date, according to DATE_FORMAT. If the parameter is valid or if it + * is empty, then the dates value are sent to the controller, in Julian Day format. + * + * @author N. Jourdane + */ public static class DateRangeField extends ParamField implements TextFieldListener { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = -7781309003911514777L; + /** The JTextField used to put the parameter minimum value of the range. */ JTextField fieldMin; + /** The JTextField used to put the parameter maximum value of the range. */ JTextField fieldMax; + /** + * Method constructor + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public DateRangeField(EpnTapMainView mainView, String paramName) { super(mainView, paramName); this.add(new JLabel("min ")); @@ -171,6 +230,9 @@ public abstract class ParamField extends JPanel { this.add(fieldMax); } + /** + * This method is called each time the field is modified. + */ @Override public void update(JTextField field) { DateFormat df = new SimpleDateFormat(DATE_FORMAT, Locale.ENGLISH); @@ -193,12 +255,27 @@ public abstract class ParamField extends JPanel { } } + /** + * The float range field is used for couples of parameter with both a `Float` class. These are + * JTextFields which check if the content is a valid float. If the parameter is valid or if it + * is empty, then the float value are sent to the controller. + * + * @author N. Jourdane + */ public static class FloatRangeField extends ParamField implements TextFieldListener { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = 7923358142882329015L; + /** The JTextField used to put the parameter minimum value of the range. */ JTextField fieldMin; + /** The JTextField used to put the parameter maximum value of the range. */ JTextField fieldMax; + /** + * Method constructor + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public FloatRangeField(EpnTapMainView mainView, String paramName) { super(mainView, paramName); fieldMin = new JTextField(); @@ -212,6 +289,9 @@ public abstract class ParamField extends JPanel { this.add(fieldMax); } + /** + * This method is called each time the field is modified. + */ @Override public void update(JTextField field) { if ("".equals(field.getText())) { @@ -229,13 +309,34 @@ public abstract class ParamField extends JPanel { } } + /** + * The target name field is used only for the `target_name` parameter. It is a ComboBox which is + * automatically filled with actual target names which begins by the entered characters, by + * asking to an online resolver (RESOLVER_URL). The parameter is sent to the controller each + * time it is updated, so it is possible to enter a parameter that the resolver do not know. + * + * @author N. Jourdane + */ public static class TargetNameField extends ParamField implements TextFieldListener { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = 5136431108894677113L; + /** The comboBox to enter the target_name and display target name propositions. */ JComboBox comboBox; + /** The JTextField related to the ComboBox, allowing to listen for text content update. */ JTextField field; + /** + * The content of the last entered value. It is used to avoid recursions, because each time + * an update event is detected, the resolver is called and the ComboBox is filled with new + * values, which trigger a new event. + */ String lastContent; + /** + * Method constructor + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public TargetNameField(EpnTapMainView mainView, String paramName) { super(mainView, paramName); comboBox = new JComboBox<>(); @@ -247,6 +348,13 @@ public abstract class ParamField extends JPanel { this.add(comboBox); } + /** + * The method used to get target names propositions by asking to the resolver. + * + * @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. + */ static String[] getItems(String begining) throws SendQueryException { StringBuilder resolverResult = null; resolverResult = VOTableConnection.sendGet(RESOLVER_URL, "q=\"" + begining + "\""); @@ -262,6 +370,10 @@ public abstract class ParamField extends JPanel { return targetNames; } + /** + * This method is called each time the field is modified. A Runnable is used it is + * impossible to modify the comboBox from a DocumentEvent. + */ Runnable updateComboBox = new Runnable() { @Override public void run() { @@ -288,41 +400,67 @@ public abstract class ParamField extends JPanel { } }; + /** + * This method is called each time the field is modified. + */ @Override public void update(JTextField textField) { SwingUtilities.invokeLater(updateComboBox); } } + /** + * The data product type field is used only for the `dataproduct_type` parameter. It is a + * ComboBox filled with a list of static data product types (see + * https://voparis-confluence.obspm.fr/display/VES/4+-+EPN-TAP+queries#id-4-EPN-TAPqueries- + * __RefHeading__35_312326667_Toc3037660444.2.4DataProductType). The parameter is sent to the + * controller each time it is updated. + * + * @author N. Jourdane + */ public static class DataProductTypeField extends ParamField { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = -6362359909898369750L; + /** The comboBox used to select the data product type. */ JComboBox comboBox; + /** + * An enumeration of all available data product types. Each values comes with an id because + * EPN-TAP table can possibly be filled with the id instead of the name, so the query have + * to ask for both of them. + * + * @author N. Jourdane + */ + @SuppressWarnings("javadoc") enum DataProductType { // @noformat - ALL("All", "all"), - IM("Image", "im"), - SP("Spectrum", "sp"), - DS("Dynamic spectrum", "ds"), - SC("Spectral cube", "sc"), - PR("Profile", "pr"), - VO("Volume", "vo"), - MO("Movie", "mo"), - CU("Cube", "cu"), - TS("Time series", "ts"), - CA("Catalog", "ca"), - SV("Spatial vector", "sv"); + ALL("All", "all"), IM("Image", "im"), SP("Spectrum", "sp"), + DS("Dynamic spectrum", "ds"), SC("Spectral cube", "sc"), PR("Profile", "pr"), + VO("Volume", "vo"), MO("Movie", "mo"), CU("Cube", "cu"), + TS("Time series", "ts"), CA("Catalog", "ca"), SV("Spatial vector", "sv"); // @format + /** The full name of the data product type, such as `Dynamic spectrum`. */ private String name = ""; + /** The id of the data product type, such as `ds`. */ private String id = ""; - DataProductType(String name, String editor) { + /** + * Method constructor for the enumeration. + * + * @param name The full name of the data product type, such as `Dynamic spectrum`. + * @param id The id of the data product type, such as `ds`. + */ + DataProductType(String name, String id) { this.name = name; - this.id = editor; + this.id = id; } + /** + * @return A list of two strings, containing the name (formated for the query) and the + * id, used in the query. A list is used instead of a array because the getQuery + * function ( @see Queries) needs to know the parameter type. + */ public List query() { List item = new ArrayList<>(); item.add(name.replace(" ", "-").toLowerCase()); @@ -336,6 +474,12 @@ public abstract class ParamField extends JPanel { } } + /** + * Method constructor + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public DataProductTypeField(EpnTapMainView mainView, String paramName) { super(mainView, paramName); comboBox = new JComboBox<>(DataProductType.values()); @@ -344,13 +488,16 @@ public abstract class ParamField extends JPanel { comboBox.addActionListener(new ActionListener() { @Override public void actionPerformed(ActionEvent e) { - onUpdate(); + update(); } }); this.add(comboBox); } - void onUpdate() { + /** + * This method is called each time the field is modified. + */ + void update() { DataProductType item = (DataProductType) comboBox.getSelectedItem(); if (DataProductType.ALL.equals(item)) { mainView.event(Event.paramRemoved, paramName); @@ -360,35 +507,61 @@ public abstract class ParamField extends JPanel { } } + /** + * The target class field is used only for the `target_class` parameter. It is a ComboBox filled + * with a list of static target classes (see + * https://voparis-confluence.obspm.fr/display/VES/4+-+EPN-TAP+queries#id-4-EPN-TAPqueries- + * __RefHeading__39_312326667_Toc3037660464.2.6TargetClass). The parameter is sent to the + * controller each time it is updated. + * + * @author N. Jourdane + */ public static class TargetClassField extends ParamField { - /** */ + /** The serial version UID (affected with a random number). */ private static final long serialVersionUID = 6439475087727685080L; + + /** The comboBox used to select the target class. */ JComboBox comboBox; + /** + * An enumeration of all available target classes. + * + * @author N. Jourdane + */ + @SuppressWarnings("javadoc") enum TargetClass { // @noformat - ALL("All"), - COMET("Comet"), - EXOPLANET("Exoplanet"), - INTERPLANETARY_MEDIUM("Interplanetary medium"), - RING("Ring"), SAMPLE("Sample"), - SKY("Sky"), - SPACECRAFT("Spacecraft"), - SPACEJUNK("Spacejunk"), - STAR("Star"); + ALL("All"), COMET("Comet"), EXOPLANET("Exoplanet"), RING("Ring"), + SAMPLE("Sample"), SKY("Sky"), SPACECRAFT("Spacecraft"), SPACEJUNK("Spacejunk"), + STAR("Star"), INTERPLANETARY_MEDIUM("Interplanetary medium"); // @format + /** The name of the target class. */ String name; + /** + * Method constructor for the enumeration. + * + * @param name The name of the target class. + */ TargetClass(String name) { this.name = name; } + /** + * @return The name formated for the query. + */ String query() { return name.replace(" ", "_").toLowerCase(); } } + /** + * Method constructor + * + * @param mainView The main view of the application. + * @param paramName The name of the parameter. + */ public TargetClassField(EpnTapMainView mainView, String paramName) { super(mainView, paramName); comboBox = new JComboBox<>(TargetClass.values()); @@ -396,13 +569,16 @@ public abstract class ParamField extends JPanel { comboBox.addActionListener(new ActionListener() { @Override public void actionPerformed(ActionEvent e) { - onUpdate(); + update(); } }); this.add(comboBox); } - void onUpdate() { + /** + * This method is called each time the field is modified. + */ + void update() { TargetClass value = (TargetClass) comboBox.getSelectedItem(); if (TargetClass.ALL.equals(value)) { mainView.event(Event.paramRemoved, paramName); @@ -412,10 +588,29 @@ public abstract class ParamField extends JPanel { } } + /** + * The listener of text field, it aims to provide a simple way to listen a text field without to + * override removeUpdate(DocumentEvent de), insertUpdate(DocumentEvent de) and + * changedUpdate(DocumentEvent de) on each field to listen. + * + * @author N. Jourdane + */ interface TextFieldListener { + /** + * When the content of the JTextField is updated. + * + * @param field The JTextField. Is useful for classes containing several text fields, such + * as DateRangeField, to know which one triggered the event. + */ void update(JTextField field); } + /** + * To add the listener. @see TextFieldListener + * + * @param changeListener The listener of text fields. + * @param field The field to listen. + */ static void addChangeListener(final TextFieldListener changeListener, final JTextField field) { field.getDocument().addDocumentListener(new DocumentListener() { @Override -- libgit2 0.21.2