Add Javadoc for ParamField.

Nathanael Jourdane
1 parent a227a22d
Showing 1 changed file with 231 additions and 36 deletions Show diff stats
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<String> 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<DataProductType> 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<String> query() {
 				List<String> 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<TargetClass> 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