Interface Survey

All Superinterfaces:
nz.org.riskscape.engine.Identified
All Known Implementing Classes:
BaseSurvey, EmptySurvey, ModelSurvey2

public interface Survey extends nz.org.riskscape.engine.Identified

Survey interface that allows the survey to act as the controller part in an MVC-style set up. This will allow us to evolve the functionality of surveys without having to make to change so much of the controller logic in the UI each time - all interactions are driven by a) getting the tree of questions based on current state b) answering a question to get the new state.

  • Field Details

    • EMPTY_SURVEY

      static final Survey EMPTY_SURVEY

      A survey that contains no questions and does nothing. An alternative to null, useful for base cases and as a default

  • Method Details

    • getSurveyMessageBundleName

      static String getSurveyMessageBundleName(String surveyId)

      Return a string that can be used as a bundle name for looking up a resource bundle / message source for a survey with the given surveyId

    • getId

      String getId()

      A unique identifier for this survey.

      Specified by:
      getId in interface nz.org.riskscape.engine.Identified
    • getMessageSource

      nz.org.riskscape.engine.i18n.MessageSource getMessageSource()

      A MessageSource that is specific to this survey. Should contain i18n text for the various choices and text associated with this survey.

    • getVersion

      default int getVersion()

      A version number that changes to indicate structural changes that might stop a previously saved version from working

    • isQuestionSetReplayOrdered

      default boolean isQuestionSetReplayOrdered()

      Returns whether or not the replay order of QuestionSets matters, i.e. returns true if QuestionSets must be replayed in the exact same order they are answered by the user. Typically, the Survey implementation itself manages the ordering of QuestionSets, drip-feeding them to the user one at a time. E.g. if the user only ever gets one QuestionSet to choose from, then the replay order doesn't matter. Ordering will matter if there are multiple QuestionSets to choose from that all apply to the same pipeline branch, e.g. replaying A then B will generate a different pipeline to replaying B then A. Note: this is only required because currently the INI parser we use does not preserve the order of the wizard answers at all.

    • getAnalysisOutputStepName

      default Optional<String> getAnalysisOutputStepName()

      Surveys should make the output of the analysis phase available at a known step name.

      This is useful to use as the input step to any reports and for the wizard command (in WizardActions) to find the available attributes to list as available once the pipeline only contains capped end steps (e.g results are saved). This occurs when the user wants to list available attributes after they have setup the first output report.

      Returns:
      the name of the analysis output step, or empty if there is none
    • getPipelineChange

      PipelineChange getPipelineChange(IncrementalBuildState buildState, Answer answer)

      Returns a PipelineChange that is created by applying an answer a build state.

      Parameters:
      buildState - the build state to get a change to.
      answer - the answer to apply. This answer must be for a question that came back from getNextQuestion(IncrementalBuildState) using the given build state, or weird things might happen
      Throws:
      InvalidAnswerException - if the answer the user supplied was invalid
    • skip

      default PipelineChange skip(IncrementalBuildState buildState, Question toSkip)

      Returns a PipelineChange that is created when skipping the given question. This might be a no-op or it might be some sort of automated change.

    • getQuestionTree

      QuestionTree getQuestionTree(IncrementalBuildState buildState)
      Returns:
      the set of questions that can be asked next. The controller code can use this question tree as a source of questions until it is empty - it shouldn't keep asking the survey for the tree between questions.
    • getNextQuestion

      default Question getNextQuestion(IncrementalBuildState buildState)

      Convenience method that'll return the next available question, or null if there are none to answer. Uses a null returning method instead of optional to allow a while-getNextQuestion-not-null construct.

    • isFinished

      boolean isFinished(IncrementalBuildState buildState)
      Returns:
      true if the survey is 'finished enough' to now run something (even if more optional question-sets remain).
    • getApplicableQuestionSets

      List<QuestionSet> getApplicableQuestionSets(IncrementalBuildState buildState)
      Returns:
      a list of the currently applicable QuestionSets, i.e. the sets of questions that are able to be answered next
    • getDefinedPhases

      default List<Phase> getDefinedPhases()
      Returns:
      a list of the phases this survey goes through, in sequence order.
    • getDescription

      default Optional<String> getDescription(Locale locale)
      Returns:
      a description for this survey, or empty of none is defined