OV-GSO-DC / EpnTAPClient

Commit b6b4fb3e346b2f3d2ecf27bd6f9ff70a57dc6f7a

Authored by Nathanael Jourdane
1 parent a227a22d
Exists in master

Add Javadoc for ParamField.

Showing 1 changed file with 231 additions and 36 deletions   Show diff stats
Inline Side-by-side
src/main/java/eu/omp/irap/vespa/epntapclient/view/ParamField.java
  Diff comments   View file @b6b4fb3
... ... @@ -46,12 +46,15 @@ import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableConnection;
46 46 import eu.omp.irap.vespa.epntapclient.votable.controller.VOTableException.SendQueryException;
47 47  
48 48 /**
49   - * A field used to set a service parameter to build the query (in the parameter panel).
  49 + * A field used to set a service parameter to build the query (in the parameter panel). ParamField
  50 + * is an abstract method and all type of parameter field should extend it. See
  51 + * https://voparis-confluence.obspm.fr/display/VES/4+-+EPN-TAP+queries to get all parameters
  52 + * details.
50 53 *
51 54 * @author N. Jourdane
52 55 */
53 56 public abstract class ParamField extends JPanel {
54   - /** */
  57 + /** The serial version UID (affected with a random number). */
55 58 private static final long serialVersionUID = 6025994164004985362L;
56 59  
57 60 /** The logger for the class ParamField. */
... ... @@ -82,6 +85,13 @@ public abstract class ParamField extends JPanel {
82 85 /** The parameter name of the field */
83 86 protected String paramName;
84 87  
  88 + /**
  89 + * Method constructor for the parameter field abstract class, which do all common action for all
  90 + * type of field, such as displaying the name of the parameter.
  91 + *
  92 + * @param mainView The main view of the application.
  93 + * @param paramName The name of the parameter.
  94 + */
85 95 public ParamField(EpnTapMainView mainView, String paramName) {
86 96 super();
87 97  
... ... @@ -97,11 +107,24 @@ public abstract class ParamField extends JPanel {
97 107 // TODO: Add tooltip text based on rr.table_column.column_description
98 108 }
99 109  
  110 + /**
  111 + * The string field is used for parameter with a `String` class. It is a simple JTextField with
  112 + * no verification. The parameter is sent to the controller each time it is modified.
  113 + *
  114 + * @author N. Jourdane
  115 + */
100 116 public static class StringField extends ParamField implements TextFieldListener {
101   - /** */
  117 + /** The serial version UID (affected with a random number). */
102 118 private static final long serialVersionUID = 24219488975302068L;
  119 + /** The JTextField used to put the parameter value. */
103 120 JTextField field;
104 121  
  122 + /**
  123 + * Method constructor for the string field.
  124 + *
  125 + * @param mainView The main view of the application.
  126 + * @param paramName The name of the parameter.
  127 + */
105 128 public StringField(EpnTapMainView mainView, String paramName) {
106 129 super(mainView, paramName);
107 130 field = new JTextField();
... ... @@ -109,6 +132,9 @@ public abstract class ParamField extends JPanel {
109 132 this.add(field);
110 133 }
111 134  
  135 + /**
  136 + * This method is called each time the field is modified.
  137 + */
112 138 @Override
113 139 public void update(JTextField textField) {
114 140 if ("".equals(textField.getText())) {
... ... @@ -119,11 +145,25 @@ public abstract class ParamField extends JPanel {
119 145 }
120 146 }
121 147  
  148 + /**
  149 + * The float field is used for parameter with a `Float` class. It is a JTextField which checks
  150 + * if the content is a valid float. If the parameter is valid or if it is empty, then the float
  151 + * value is sent to the controller.
  152 + *
  153 + * @author N. Jourdane
  154 + */
122 155 public static class FloatField extends ParamField implements TextFieldListener {
123   - /** */
  156 + /** The serial version UID (affected with a random number). */
124 157 private static final long serialVersionUID = -1880193152285564590L;
  158 + /** The JTextField used to put the parameter value. */
125 159 JTextField field;
126 160  
  161 + /**
  162 + * Method constructor
  163 + *
  164 + * @param mainView The main view of the application.
  165 + * @param paramName The name of the parameter.
  166 + */
127 167 public FloatField(EpnTapMainView mainView, String paramName) {
128 168 super(mainView, paramName);
129 169 field = new JTextField();
... ... @@ -131,6 +171,9 @@ public abstract class ParamField extends JPanel {
131 171 this.add(field);
132 172 }
133 173  
  174 + /**
  175 + * This method is called each time the field is modified.
  176 + */
134 177 @Override
135 178 public void update(JTextField textField) {
136 179 if ("".equals(textField.getText())) {
... ... @@ -148,12 +191,28 @@ public abstract class ParamField extends JPanel {
148 191 }
149 192 }
150 193  
  194 + /**
  195 + * The date range field is used for couples of parameter with both a `Date` type (actually only
  196 + * `time_min` and `time_max` parameters is concerned for now). These are JTextFields which check
  197 + * if the content is a valid date, according to DATE_FORMAT. If the parameter is valid or if it
  198 + * is empty, then the dates value are sent to the controller, in Julian Day format.
  199 + *
  200 + * @author N. Jourdane
  201 + */
151 202 public static class DateRangeField extends ParamField implements TextFieldListener {
152   - /** */
  203 + /** The serial version UID (affected with a random number). */
153 204 private static final long serialVersionUID = -7781309003911514777L;
  205 + /** The JTextField used to put the parameter minimum value of the range. */
154 206 JTextField fieldMin;
  207 + /** The JTextField used to put the parameter maximum value of the range. */
155 208 JTextField fieldMax;
156 209  
  210 + /**
  211 + * Method constructor
  212 + *
  213 + * @param mainView The main view of the application.
  214 + * @param paramName The name of the parameter.
  215 + */
157 216 public DateRangeField(EpnTapMainView mainView, String paramName) {
158 217 super(mainView, paramName);
159 218 this.add(new JLabel("min "));
... ... @@ -171,6 +230,9 @@ public abstract class ParamField extends JPanel {
171 230 this.add(fieldMax);
172 231 }
173 232  
  233 + /**
  234 + * This method is called each time the field is modified.
  235 + */
174 236 @Override
175 237 public void update(JTextField field) {
176 238 DateFormat df = new SimpleDateFormat(DATE_FORMAT, Locale.ENGLISH);
... ... @@ -193,12 +255,27 @@ public abstract class ParamField extends JPanel {
193 255 }
194 256 }
195 257  
  258 + /**
  259 + * The float range field is used for couples of parameter with both a `Float` class. These are
  260 + * JTextFields which check if the content is a valid float. If the parameter is valid or if it
  261 + * is empty, then the float value are sent to the controller.
  262 + *
  263 + * @author N. Jourdane
  264 + */
196 265 public static class FloatRangeField extends ParamField implements TextFieldListener {
197   - /** */
  266 + /** The serial version UID (affected with a random number). */
198 267 private static final long serialVersionUID = 7923358142882329015L;
  268 + /** The JTextField used to put the parameter minimum value of the range. */
199 269 JTextField fieldMin;
  270 + /** The JTextField used to put the parameter maximum value of the range. */
200 271 JTextField fieldMax;
201 272  
  273 + /**
  274 + * Method constructor
  275 + *
  276 + * @param mainView The main view of the application.
  277 + * @param paramName The name of the parameter.
  278 + */
202 279 public FloatRangeField(EpnTapMainView mainView, String paramName) {
203 280 super(mainView, paramName);
204 281 fieldMin = new JTextField();
... ... @@ -212,6 +289,9 @@ public abstract class ParamField extends JPanel {
212 289 this.add(fieldMax);
213 290 }
214 291  
  292 + /**
  293 + * This method is called each time the field is modified.
  294 + */
215 295 @Override
216 296 public void update(JTextField field) {
217 297 if ("".equals(field.getText())) {
... ... @@ -229,13 +309,34 @@ public abstract class ParamField extends JPanel {
229 309 }
230 310 }
231 311  
  312 + /**
  313 + * The target name field is used only for the `target_name` parameter. It is a ComboBox which is
  314 + * automatically filled with actual target names which begins by the entered characters, by
  315 + * asking to an online resolver (RESOLVER_URL). The parameter is sent to the controller each
  316 + * time it is updated, so it is possible to enter a parameter that the resolver do not know.
  317 + *
  318 + * @author N. Jourdane
  319 + */
232 320 public static class TargetNameField extends ParamField implements TextFieldListener {
233   - /** */
  321 + /** The serial version UID (affected with a random number). */
234 322 private static final long serialVersionUID = 5136431108894677113L;
  323 + /** The comboBox to enter the target_name and display target name propositions. */
235 324 JComboBox<String> comboBox;
  325 + /** The JTextField related to the ComboBox, allowing to listen for text content update. */
236 326 JTextField field;
  327 + /**
  328 + * The content of the last entered value. It is used to avoid recursions, because each time
  329 + * an update event is detected, the resolver is called and the ComboBox is filled with new
  330 + * values, which trigger a new event.
  331 + */
237 332 String lastContent;
238 333  
  334 + /**
  335 + * Method constructor
  336 + *
  337 + * @param mainView The main view of the application.
  338 + * @param paramName The name of the parameter.
  339 + */
239 340 public TargetNameField(EpnTapMainView mainView, String paramName) {
240 341 super(mainView, paramName);
241 342 comboBox = new JComboBox<>();
... ... @@ -247,6 +348,13 @@ public abstract class ParamField extends JPanel {
247 348 this.add(comboBox);
248 349 }
249 350  
  351 + /**
  352 + * The method used to get target names propositions by asking to the resolver.
  353 + *
  354 + * @param begining The beginning of the target_name.
  355 + * @return An array of Strings corresponding to the target names got.
  356 + * @throws SendQueryException If the resolver do not work.
  357 + */
250 358 static String[] getItems(String begining) throws SendQueryException {
251 359 StringBuilder resolverResult = null;
252 360 resolverResult = VOTableConnection.sendGet(RESOLVER_URL, "q=\"" + begining + "\"");
... ... @@ -262,6 +370,10 @@ public abstract class ParamField extends JPanel {
262 370 return targetNames;
263 371 }
264 372  
  373 + /**
  374 + * This method is called each time the field is modified. A Runnable is used it is
  375 + * impossible to modify the comboBox from a DocumentEvent.
  376 + */
265 377 Runnable updateComboBox = new Runnable() {
266 378 @Override
267 379 public void run() {
... ... @@ -288,41 +400,67 @@ public abstract class ParamField extends JPanel {
288 400 }
289 401 };
290 402  
  403 + /**
  404 + * This method is called each time the field is modified.
  405 + */
291 406 @Override
292 407 public void update(JTextField textField) {
293 408 SwingUtilities.invokeLater(updateComboBox);
294 409 }
295 410 }
296 411  
  412 + /**
  413 + * The data product type field is used only for the `dataproduct_type` parameter. It is a
  414 + * ComboBox filled with a list of static data product types (see
  415 + * https://voparis-confluence.obspm.fr/display/VES/4+-+EPN-TAP+queries#id-4-EPN-TAPqueries-
  416 + * __RefHeading__35_312326667_Toc3037660444.2.4DataProductType). The parameter is sent to the
  417 + * controller each time it is updated.
  418 + *
  419 + * @author N. Jourdane
  420 + */
297 421 public static class DataProductTypeField extends ParamField {
298   - /** */
  422 + /** The serial version UID (affected with a random number). */
299 423 private static final long serialVersionUID = -6362359909898369750L;
  424 + /** The comboBox used to select the data product type. */
300 425 JComboBox<DataProductType> comboBox;
301 426  
  427 + /**
  428 + * An enumeration of all available data product types. Each values comes with an id because
  429 + * EPN-TAP table can possibly be filled with the id instead of the name, so the query have
  430 + * to ask for both of them.
  431 + *
  432 + * @author N. Jourdane
  433 + */
  434 + @SuppressWarnings("javadoc")
302 435 enum DataProductType {
303 436 // @noformat
304   - ALL("All", "all"),
305   - IM("Image", "im"),
306   - SP("Spectrum", "sp"),
307   - DS("Dynamic spectrum", "ds"),
308   - SC("Spectral cube", "sc"),
309   - PR("Profile", "pr"),
310   - VO("Volume", "vo"),
311   - MO("Movie", "mo"),
312   - CU("Cube", "cu"),
313   - TS("Time series", "ts"),
314   - CA("Catalog", "ca"),
315   - SV("Spatial vector", "sv");
  437 + ALL("All", "all"), IM("Image", "im"), SP("Spectrum", "sp"),
  438 + DS("Dynamic spectrum", "ds"), SC("Spectral cube", "sc"), PR("Profile", "pr"),
  439 + VO("Volume", "vo"), MO("Movie", "mo"), CU("Cube", "cu"),
  440 + TS("Time series", "ts"), CA("Catalog", "ca"), SV("Spatial vector", "sv");
316 441 // @format
317 442  
  443 + /** The full name of the data product type, such as `Dynamic spectrum`. */
318 444 private String name = "";
  445 + /** The id of the data product type, such as `ds`. */
319 446 private String id = "";
320 447  
321   - DataProductType(String name, String editor) {
  448 + /**
  449 + * Method constructor for the enumeration.
  450 + *
  451 + * @param name The full name of the data product type, such as `Dynamic spectrum`.
  452 + * @param id The id of the data product type, such as `ds`.
  453 + */
  454 + DataProductType(String name, String id) {
322 455 this.name = name;
323   - this.id = editor;
  456 + this.id = id;
324 457 }
325 458  
  459 + /**
  460 + * @return A list of two strings, containing the name (formated for the query) and the
  461 + * id, used in the query. A list is used instead of a array because the getQuery
  462 + * function ( @see Queries) needs to know the parameter type.
  463 + */
326 464 public List<String> query() {
327 465 List<String> item = new ArrayList<>();
328 466 item.add(name.replace(" ", "-").toLowerCase());
... ... @@ -336,6 +474,12 @@ public abstract class ParamField extends JPanel {
336 474 }
337 475 }
338 476  
  477 + /**
  478 + * Method constructor
  479 + *
  480 + * @param mainView The main view of the application.
  481 + * @param paramName The name of the parameter.
  482 + */
339 483 public DataProductTypeField(EpnTapMainView mainView, String paramName) {
340 484 super(mainView, paramName);
341 485 comboBox = new JComboBox<>(DataProductType.values());
... ... @@ -344,13 +488,16 @@ public abstract class ParamField extends JPanel {
344 488 comboBox.addActionListener(new ActionListener() {
345 489 @Override
346 490 public void actionPerformed(ActionEvent e) {
347   - onUpdate();
  491 + update();
348 492 }
349 493 });
350 494 this.add(comboBox);
351 495 }
352 496  
353   - void onUpdate() {
  497 + /**
  498 + * This method is called each time the field is modified.
  499 + */
  500 + void update() {
354 501 DataProductType item = (DataProductType) comboBox.getSelectedItem();
355 502 if (DataProductType.ALL.equals(item)) {
356 503 mainView.event(Event.paramRemoved, paramName);
... ... @@ -360,35 +507,61 @@ public abstract class ParamField extends JPanel {
360 507 }
361 508 }
362 509  
  510 + /**
  511 + * The target class field is used only for the `target_class` parameter. It is a ComboBox filled
  512 + * with a list of static target classes (see
  513 + * https://voparis-confluence.obspm.fr/display/VES/4+-+EPN-TAP+queries#id-4-EPN-TAPqueries-
  514 + * __RefHeading__39_312326667_Toc3037660464.2.6TargetClass). The parameter is sent to the
  515 + * controller each time it is updated.
  516 + *
  517 + * @author N. Jourdane
  518 + */
363 519 public static class TargetClassField extends ParamField {
364   - /** */
  520 + /** The serial version UID (affected with a random number). */
365 521 private static final long serialVersionUID = 6439475087727685080L;
  522 +
  523 + /** The comboBox used to select the target class. */
366 524 JComboBox<TargetClass> comboBox;
367 525  
  526 + /**
  527 + * An enumeration of all available target classes.
  528 + *
  529 + * @author N. Jourdane
  530 + */
  531 + @SuppressWarnings("javadoc")
368 532 enum TargetClass {
369 533 // @noformat
370   - ALL("All"),
371   - COMET("Comet"),
372   - EXOPLANET("Exoplanet"),
373   - INTERPLANETARY_MEDIUM("Interplanetary medium"),
374   - RING("Ring"), SAMPLE("Sample"),
375   - SKY("Sky"),
376   - SPACECRAFT("Spacecraft"),
377   - SPACEJUNK("Spacejunk"),
378   - STAR("Star");
  534 + ALL("All"), COMET("Comet"), EXOPLANET("Exoplanet"), RING("Ring"),
  535 + SAMPLE("Sample"), SKY("Sky"), SPACECRAFT("Spacecraft"), SPACEJUNK("Spacejunk"),
  536 + STAR("Star"), INTERPLANETARY_MEDIUM("Interplanetary medium");
379 537 // @format
380 538  
  539 + /** The name of the target class. */
381 540 String name;
382 541  
  542 + /**
  543 + * Method constructor for the enumeration.
  544 + *
  545 + * @param name The name of the target class.
  546 + */
383 547 TargetClass(String name) {
384 548 this.name = name;
385 549 }
386 550  
  551 + /**
  552 + * @return The name formated for the query.
  553 + */
387 554 String query() {
388 555 return name.replace(" ", "_").toLowerCase();
389 556 }
390 557 }
391 558  
  559 + /**
  560 + * Method constructor
  561 + *
  562 + * @param mainView The main view of the application.
  563 + * @param paramName The name of the parameter.
  564 + */
392 565 public TargetClassField(EpnTapMainView mainView, String paramName) {
393 566 super(mainView, paramName);
394 567 comboBox = new JComboBox<>(TargetClass.values());
... ... @@ -396,13 +569,16 @@ public abstract class ParamField extends JPanel {
396 569 comboBox.addActionListener(new ActionListener() {
397 570 @Override
398 571 public void actionPerformed(ActionEvent e) {
399   - onUpdate();
  572 + update();
400 573 }
401 574 });
402 575 this.add(comboBox);
403 576 }
404 577  
405   - void onUpdate() {
  578 + /**
  579 + * This method is called each time the field is modified.
  580 + */
  581 + void update() {
406 582 TargetClass value = (TargetClass) comboBox.getSelectedItem();
407 583 if (TargetClass.ALL.equals(value)) {
408 584 mainView.event(Event.paramRemoved, paramName);
... ... @@ -412,10 +588,29 @@ public abstract class ParamField extends JPanel {
412 588 }
413 589 }
414 590  
  591 + /**
  592 + * The listener of text field, it aims to provide a simple way to listen a text field without to
  593 + * override removeUpdate(DocumentEvent de), insertUpdate(DocumentEvent de) and
  594 + * changedUpdate(DocumentEvent de) on each field to listen.
  595 + *
  596 + * @author N. Jourdane
  597 + */
415 598 interface TextFieldListener {
  599 + /**
  600 + * When the content of the JTextField is updated.
  601 + *
  602 + * @param field The JTextField. Is useful for classes containing several text fields, such
  603 + * as DateRangeField, to know which one triggered the event.
  604 + */
416 605 void update(JTextField field);
417 606 }
418 607  
  608 + /**
  609 + * To add the listener. @see TextFieldListener
  610 + *
  611 + * @param changeListener The listener of text fields.
  612 + * @param field The field to listen.
  613 + */
419 614 static void addChangeListener(final TextFieldListener changeListener, final JTextField field) {
420 615 field.getDocument().addDocumentListener(new DocumentListener() {
421 616 @Override
... ...