1 /*
   2  * $Id$
   3  *
   4  * Copyright (c) 2001, 2011, Oracle and/or its affiliates. All rights reserved.
   5  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6  *
   7  * This code is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License version 2 only, as
   9  * published by the Free Software Foundation.  Oracle designates this
  10  * particular file as subject to the "Classpath" exception as provided
  11  * by Oracle in the LICENSE file that accompanied this code.
  12  *
  13  * This code is distributed in the hope that it will be useful, but WITHOUT
  14  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * version 2 for more details (a copy is included in the LICENSE file that
  17  * accompanied this code).
  18  *
  19  * You should have received a copy of the GNU General Public License version
  20  * 2 along with this work; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  22  *
  23  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  24  * or visit www.oracle.com if you need additional information or have any
  25  * questions.
  26  */
  27 package com.sun.interview;
  28 
  29 import java.text.MessageFormat;
  30 import java.util.Map;
  31 import java.util.ResourceBundle;
  32 import java.util.Vector;
  33 
  34 /**
  35  * A {@link Question question} to support the construction of an
  36  * open-ended set of complex values determined by a specified subinterview.
  37  *
  38  * <p>A "loop" is created by creating an instance of a subtype of ListQuestion.
  39  * The subtype must implement createBody() to create instances of the subinterview
  40  * for the body of the loop. getNext() should return the next question after the
  41  * loop has been completed.
  42  *
  43  * <p>Computationally, this question behaves more like a "fork" than a "loop".
  44  * Semantically, it is as though all the bodies are evaluated together,
  45  * in parallel, rather than serially one after the other.
  46  * In the  GUI presentation, it is expected that only one body is displayed
  47  * at a time, and that the user can choose which body is viewed.
  48  * This avoids having all the loops unrolled all the time in the display of
  49  * the current path.
  50  * Internally, each ListQuestion has a sibling that is created automatically,
  51  * and together, these two questions bracket the set of loop bodies.
  52  */
  53 public abstract class ListQuestion extends Question
  54 {
  55     /**
  56      * A special subtype of Interview to use for the questions in the body of
  57      * a loop. The body has an index, which identifies its position within
  58      * the list of current loop bodies, and a summary string to identify
  59      * this instance of the loop body.
  60      */
  61     public static abstract class Body extends Interview {
  62         /**
  63          * Create an instance of a loop body.
  64          * @param question The loop question for which this is a body instance.
  65          * @param index The position of this body within the set of all the bodies.
  66          * The value is normally just a hint (albeit a possibly string one).
  67          * The index will be updated if necessary when the body is actually
  68          * set as one of the bodies of the loop.
  69          */
  70         protected Body(ListQuestion question, int index) {
  71             super(question.getInterview(),
  72                   question.getBaseTag() + "." + index);
  73             this.question = question;
  74             this.index = index;
  75         }
  76 
  77         /**
  78          * Get a string to uniquely identify this instance of the loop body,
  79          * or null if there is insufficient information so far to make a
  80          * determination. The string will be used to identify the loop body
  81          * to the user.
  82          * @return a string to uniquely identify this instance of the loop body,
  83          * or null if there is insufficient information so far to make a
  84          * determination.
  85          */
  86         public abstract String getSummary();
  87 
  88         /**
  89          * Get the position of this loop body within the set of all the loop
  90          * bodies for the question.
  91          * @return the position of this loop body within the set of all the loop
  92          * bodies for the question
  93          */
  94         public int getIndex() {
  95             return index;
  96         }
  97 
  98         /**
  99          * Set the recorded position of this loop body within the set
 100          * of all the loop bodies for the question. By itself, this method
 101          * does not actually affect the loop bodies.
 102          * See {@link ListQuestion#setBodies} for details on updating the
 103          * bodies of the loop.
 104          * @param newIndex the new position of this loop body within the
 105          * set of all the loop bodies for the question
 106          */
 107         void setIndex(int newIndex) {
 108             if (newIndex != index) {
 109                 index = newIndex;
 110                 setBaseTag(question.getBaseTag() + "." + index);
 111             }
 112         }
 113 
 114         /**
 115          * Get a default summary to be used to identify this instance of the
 116          * the loop body, to be used when getSummary() returns null.
 117          * The summary will be a standard prefix string possibly followed
 118          * by a number to distinguish between multiple bodies using the
 119          * default summary. The default summary will be unique and persist
 120          * for the life of this body or until getSummary() returns a non-null
 121          * value.
 122          * @return a default summary to be used to identify this instance of the
 123          * the loop body, to be used when getSummary() returns null.
 124          */
 125         public String getDefaultSummary() {
 126             if (defaultSummary == null) {
 127                 // recycle any default summaries that are no longer required
 128                 Vector bodies = question.bodies;
 129                 for (int i = 0; i < bodies.size(); i++) {
 130                     Body b = (Body) (bodies.elementAt(i));
 131                     if (b.defaultSummary != null
 132                         && b.getSummary() != null
 133                         && !b.defaultSummary.equals(b.getSummary())) {
 134                         b.defaultSummary = null;
 135                     }
 136                 }
 137 
 138                 // try and find an unused unique value v not used by any other default summary
 139                 for (int v = 0; v < bodies.size(); v++) {
 140                     String s = MessageFormat.format(i18n.getString("lp.newValue"),
 141                                                     new Object[] { new Integer(v) });
 142                     // check s is not the same as any current default summary;
 143                     // if it is, reset it to null
 144                     for (int i = 0; i < bodies.size(); i++) {
 145                         Body b = (Body) (bodies.elementAt(i));
 146                         if (s.equals(b.defaultSummary)) {
 147                             s = null;
 148                             break;
 149                         }
 150                     }
 151                     // if s is not null, it is unique, different from other default
 152                     // summaries, so use it...
 153                     if (s != null) {
 154                         defaultSummary = s;
 155                         break;
 156                     }
 157                 }
 158             }
 159 
 160             return defaultSummary;
 161         }
 162 
 163         /**
 164          * Check if this body has been completed. It is considered to have
 165          * been completed if none of the questions in this body
 166          * on the current path return null as the result of getNext().
 167          * @return true is this body has been completed.
 168          */
 169         public boolean isBodyFinishable() {
 170             return isInterviewFinishable();
 171         }
 172 
 173         private ListQuestion question;
 174         private int index;
 175         private String defaultSummary;
 176     };
 177 
 178     /**
 179      * Create a question with a nominated tag.
 180      * @param interview The interview containing this question.
 181      * @param tag A unique tag to identify this specific question.
 182      */
 183     protected ListQuestion(Interview interview, String tag) {
 184         super(interview, tag);
 185 
 186         if (this instanceof EndQuestion) {
 187             end = (EndQuestion) this;
 188             bodies = null;
 189         }
 190         else {
 191             end = new EndQuestion(interview, tag, this);
 192             bodies = new Vector<>();
 193         }
 194     }
 195 
 196     /**
 197      * Create a new instance of a body for this loop question.
 198      * The body is a subinterview that contains the questions
 199      * for the body of the loop.
 200      * The body does not become one of the set of bodies for the loop
 201      * until the set is updated with {@link #setBodies}.
 202      * @param index the position that this body will have within
 203      * the set of bodies for the loop. This value should be passed
 204      * through to the Body constructor.
 205      * @return a new instance of a body for this loop question
 206      */
 207     public abstract Body createBody(int index);
 208 
 209     /**
 210      * Check if this is the question that appears at the beginning or
 211      * at the end of the loop. When a ListQuestion is created, a sibling
 212      * is automatically created that will appear at the end of the loop.
 213      * @return false if this is the main question, that appears at the
 214      * head of the loop, or true if this is the question that is
 215      * automatically created to appear at the end of the lop.
 216      */
 217     public final boolean isEnd() {
 218         return (this instanceof EndQuestion);
 219     }
 220 
 221     /**
 222      * Get the sibling question that appears at the other end of the loop.
 223      * When a ListQuestion is created, a sibling is automatically created
 224      * that will appear at the end of the loop. From either of these questions,
 225      * you can use this method to get at the other one.
 226      * @return the sibling question that appears at the other end of the loop
 227      */
 228     public ListQuestion getOther() {
 229         return end;
 230     }
 231 
 232     /**
 233      * Get the currently selected loop body, or null, as selected by by setValue.
 234      * @return the currently selected loop body, or null, if none.
 235      */
 236     public Body getSelectedBody() {
 237         if (value >= 0 && value < bodies.size())
 238             return bodies.elementAt(value);
 239         else
 240             return null;
 241     }
 242 
 243     /**
 244      * Get the index of the currently selected loop body, or an out of range
 245      * value (typically less than zero) if none is selected.
 246      * @return the index of the currently selected loop body, or an out of range
 247      * value (typically less than zero) if none is selected
 248      * @see #setValue
 249      */
 250     public int getValue() {
 251         return value;
 252     }
 253 
 254     /**
 255      * Verify this question is on the current path, and if it is,
 256      * return the current value.
 257      * @return the current value of this question
 258      * @throws Interview.NotOnPathFault if this question is not on the
 259      * current path
 260      * @see #getValue
 261      */
 262     public int getValueOnPath()
 263         throws Interview.NotOnPathFault
 264     {
 265         interview.verifyPathContains(this);
 266         return getValue();
 267     }
 268 
 269     /**
 270      * Get a string representation of the index of the currently
 271      * selected loop body, or an out of range value
 272      * (typically less than zero) if none is selected.
 273      */
 274     public String getStringValue() {
 275         return String.valueOf(value);
 276     }
 277 
 278     /**
 279      * Set the index of the loop body to be selected.
 280      * If the value is out of range, no loop body will be selected.
 281      * @param newValue the index of the loop body to be selected
 282      * @see #getValue
 283      */
 284     public void setValue(int newValue) {
 285         int oldValue = value;
 286         value = newValue;
 287         if (normalizeValue(value) != normalizeValue(oldValue)) {
 288             interview.updatePath(this);
 289             interview.setEdited(true);
 290         }
 291     }
 292 
 293     private int normalizeValue(int value) {
 294         return (value >= 0 && value < bodies.size() ? value : -1);
 295     }
 296 
 297     /**
 298      * Set the index of the loop body to be selected.
 299      * If the value is out of range, no loop body will be selected.
 300      * @param s a string containing the index of the loop body
 301      * to be selected. If the string does not contain a valid
 302      * integer, the value will be set to -1.
 303      * @see #getValue
 304      */
 305     public void setValue(String s) {
 306         try {
 307             if (s != null) {
 308                 setValue(Integer.parseInt(s));
 309                 return;
 310             }
 311         }
 312         catch (NumberFormatException e) {
 313             // ignore
 314         }
 315         setValue(-1);
 316     }
 317 
 318     /**
 319      * Check if the question currently has a valid response.
 320      * For a ListQuestion, this is normally true.
 321      * @return true if the question currently has a valid response,
 322      * and false otherwise.
 323      **/
 324     public boolean isValueValid() {
 325         return true;  // should probably reflect whether bodies are valid
 326     }
 327 
 328     /**
 329      * Check if the question always has a valid response.
 330      * For a ListQuestion, this is normally false.
 331      * @return true if the question always has a valid response,
 332      * and false otherwise.
 333      **/
 334     public boolean isValueAlwaysValid() {
 335         return false;
 336     }
 337 
 338     /**
 339      * Remove all the bodies currently allocated for this question,
 340      * and set the value of the question to indicate no loop
 341      * body selected.
 342      */
 343     public void clear() {
 344         setValue(Integer.MIN_VALUE);
 345         bodies.setSize(0);
 346     }
 347 
 348     /**
 349      * Get the summary text for the end question.
 350      * When a ListQuestion is created, a sibling is automatically created
 351      * that will appear at the end of the loop.
 352      * Override this method to override the default behavior to
 353      * get the summary text from the standard resource bundle.
 354      * The tag for the end question is the same as the tag for the
 355      * main question, with ".end" appended.
 356      * @return the summary text for the end question
 357      * @see #getSummary
 358      * @see #getOther
 359      */
 360     public String getEndSummary() {
 361         return end.getDefaultSummary();
 362     }
 363 
 364     /**
 365      * Get the question text for the end question.
 366      * When a ListQuestion is created, a sibling is automatically created
 367      * that will appear at the end of the loop.
 368      * Override this method to override the default behavior to
 369      * get the question text from the standard resource bundle.
 370      * The tag for the end question is the same as the tag for the
 371      * main question, with ".end" appended.
 372      * @return the question text for the end question
 373      * @see #getEndTextArgs
 374      * @see #getText
 375      * @see #getOther
 376      */
 377     public String getEndText() {
 378         return end.getDefaultText();
 379     }
 380 
 381 
 382     /**
 383      * Get the formatting arguments for the question text for the end question.
 384      * When a ListQuestion is created, a sibling is automatically created
 385      * that will appear at the end of the loop.
 386      * Override this method to override the default behavior to
 387      * return null.
 388      * @return the formatting arguments for the question text for the end question
 389      * @see #getEndText
 390      * @see #getTextArgs
 391      * @see #getOther
 392      */
 393     public Object[] getEndTextArgs() {
 394         return end.getDefaultTextArgs();
 395     }
 396 
 397     protected void load(Map<String, String> data) {
 398         bodies.setSize(0);
 399         String c = data.get(tag + ".count");
 400         if (c != null && c.length() > 0) {
 401             try {
 402                 int n = Integer.parseInt(c);
 403                 for (int i = 0; i < n; i++)
 404                     bodies.add(createBody(i));
 405                 // once the bodies are created as children of this question's
 406                 // interview, they'll be reloaded by the interviews load method
 407             }
 408             catch (NumberFormatException ignore) {
 409             }
 410         }
 411 
 412         String v = data.get(tag + ".curr");
 413         if (v == null || v.length() == 0)
 414             value = 0;
 415         else {
 416             try {
 417                 value = Integer.parseInt(v);
 418             }
 419             catch (NumberFormatException ignore) {
 420                 value = 0;
 421             }
 422         }
 423     }
 424 
 425     protected void save(Map<String, String> data) {
 426         data.put(tag + ".count", String.valueOf(bodies.size()));
 427         data.put(tag + ".curr", String.valueOf(value));
 428     }
 429 
 430     /**
 431      * Get the set of bodies currently allocated within the loop.
 432      * @return the set of bodies currently allocated within the loop
 433      * @see #setBodies
 434      */
 435     public Body[] getBodies() {
 436         Body[] b = new Body[bodies.size()];
 437         bodies.copyInto(b);
 438         return b;
 439     }
 440 
 441     /**
 442      * Get the number of bodies (iterations) currently allocated within the loop.
 443      * @return the number of bodies currently allocated within the loop
 444      */
 445     public int getBodyCount() {
 446         return (bodies == null ? 0 : bodies.size());
 447     }
 448 
 449     /**
 450      * Get a specified body from the loop.
 451      * @param index the position of the desired body within the set of bodies
 452      * currently allocated within the loop.
 453      * @return the specified body
 454      * @throws ArrayIndexOutOfBoundsException if index does not identify a
 455      * valid body
 456      */
 457     public Body getBody(int index) {
 458         return bodies.elementAt(index);
 459     }
 460 
 461     /**
 462      * Set the set of bodies allocated within the loop, and the
 463      * index of one which should be selected.
 464      * The bodies will normally come from a combination of
 465      * the bodies returned from getBodies() or new ones
 466      * created by createBody().
 467      * @param newBodies the set of bodies to be taken as the
 468      * new set of loop bodies
 469      * @param newValue the index of the body which should be
 470      * the selected body.
 471      * @see #getBodies
 472      */
 473     public void setBodies(Body[] newBodies, int newValue) {
 474         Body oldSelectedBody = getSelectedBody();
 475         int oldIncompleteCount = getIncompleteBodyCount();
 476 
 477         boolean edited = false;
 478 
 479         if (newBodies.length != bodies.size()) {
 480             bodies.setSize(newBodies.length);
 481             edited = true;
 482         }
 483 
 484         for (int i = 0; i < newBodies.length; i++) {
 485             Body b = newBodies[i];
 486             if (b != bodies.elementAt(i)) {
 487                 b.setIndex(i);
 488                 bodies.setElementAt(b, i);
 489                 edited = true;
 490             }
 491         }
 492 
 493         value = newValue;
 494         Body newSelectedBody = getSelectedBody();
 495         int newIncompleteCount = getIncompleteBodyCount();
 496 
 497         if (newSelectedBody != oldSelectedBody
 498             || ((oldIncompleteCount == 0) != (newIncompleteCount == 0))) {
 499             interview.updatePath(this);
 500         }
 501 
 502         interview.setEdited(edited);
 503     }
 504 
 505     /**
 506      * Get the number of bodies for this loop that are currently incomplete,
 507      * as determined by {@link  Body#isBodyFinishable}.
 508      * @return the number of bodies for this loop that are currently incomplete.
 509      */
 510     public int getIncompleteBodyCount() {
 511         int count = 0;
 512         for (int i = 0; i < bodies.size(); i++) {
 513             Body b = bodies.elementAt(i);
 514             if (!b.isInterviewFinishable())
 515                 count++;
 516         }
 517         return count;
 518     }
 519 
 520 
 521     private final EndQuestion end;
 522     private final Vector<Body> bodies;
 523     private int value;
 524 
 525     private static final ResourceBundle i18n = Interview.i18n;
 526 
 527     private static class EndQuestion extends ListQuestion {
 528         EndQuestion(Interview interview, String tag, ListQuestion head) {
 529             super(interview, tag + ".end");
 530             this.head = head;
 531         }
 532 
 533         public Question getNext() {
 534             boolean allBodiesFinishable = true;
 535             for (int i = 0; i < head.getBodyCount(); i++) {
 536                 Body b = head.getBody(i);
 537                 if (!b.isInterviewFinishable()) {
 538                     allBodiesFinishable = false;
 539                     break;
 540                 }
 541             }
 542 
 543             return (allBodiesFinishable ? head.getNext() : null);
 544         }
 545 
 546         public String getSummary() {
 547             // ListQuestion.getEndSummary can be overridden, but defaults to
 548             // getDefaultSummary() here, which calls super.getSummary()
 549             return head.getEndSummary();
 550         }
 551 
 552         String getDefaultSummary() {
 553             return super.getSummary();
 554         }
 555 
 556         public String getText() {
 557             // ListQuestion.getEndText can be overridden, but defaults to
 558             // getDefaultText() here, which calls super.getText()
 559             return head.getEndText();
 560         }
 561 
 562         String getDefaultText() {
 563             return super.getText();
 564         }
 565 
 566         public Object[] getTextArgs() {
 567             // ListQuestion.getEndTextArgs can be overridden, but defaults to
 568             // getDefaultTextArgs() here, which calls super.getText()
 569             return head.getEndTextArgs();
 570         }
 571 
 572         Object[] getDefaultTextArgs() {
 573             return super.getTextArgs();
 574         }
 575 
 576         public int getValue() {
 577             return head.getValue();
 578         }
 579 
 580         public String getStringValue() {
 581             return head.getStringValue();
 582         }
 583 
 584         public void setValue(int value) {
 585             head.setValue(value);
 586         }
 587 
 588         public void setValue(String s) {
 589             head.setValue(s);
 590         }
 591 
 592         public Body getSelectedBody() {
 593             return head.getSelectedBody();
 594         }
 595 
 596         public Body createBody(int index) {
 597             return head.createBody(index);
 598         }
 599 
 600         public ListQuestion getOther() {
 601             return head;
 602         }
 603 
 604         public void clear() {
 605             head.clear();
 606         }
 607 
 608         protected void load(Map<String, String> data) {
 609         }
 610 
 611         protected void save(Map<String, String> data) {
 612         }
 613 
 614         public Body[] getBodies() {
 615             return head.getBodies();
 616         }
 617 
 618         public int getBodyCount() {
 619             return head.getBodyCount();
 620         }
 621 
 622         public Body getBody(int index) {
 623             return head.getBody(index);
 624         }
 625 
 626         public void setBodies(Body[] newBodies, int newValue) {
 627             head.setBodies(newBodies, newValue);
 628         }
 629 
 630         public int getIncompleteBodyCount() {
 631             return head.getIncompleteBodyCount();
 632         }
 633 
 634         private ListQuestion head;
 635 
 636     }
 637 }