src/main/java/com/indexdata/pz2utils4jsf/pazpar2/Pz2Interface.java

   1 package com.indexdata.pz2utils4jsf.pazpar2;\r
   2 \r
   3 import java.io.Serializable;\r
   4 import java.util.List;\r
   5 \r
   6 import com.indexdata.pz2utils4jsf.controls.ResultsPager;\r
   7 import com.indexdata.pz2utils4jsf.errors.ErrorInterface;\r
   8 import com.indexdata.pz2utils4jsf.pazpar2.data.ByTarget;\r
   9 import com.indexdata.pz2utils4jsf.pazpar2.data.RecordResponse;\r
  10 import com.indexdata.pz2utils4jsf.pazpar2.data.ShowResponse;\r
  11 import com.indexdata.pz2utils4jsf.pazpar2.data.StatResponse;\r
  12 import com.indexdata.pz2utils4jsf.pazpar2.data.TermListsResponse;\r
  13 import com.indexdata.pz2utils4jsf.pazpar2.data.TermResponse;\r
  14 \r
  15 public interface Pz2Interface extends Serializable {\r
  16 \r
  17   /**\r
  18    * Executes a Pazpar2 search using the given query string\r
  19    * \r
  20    * @param query\r
  21    */\r
  22   public void doSearch(String query);\r
  23   \r
  24   /**\r
  25    * Executes a Pazpar2 search using the current query \r
  26    */\r
  27   public void doSearch();\r
  28   \r
  29   /**\r
  30    * Updates display data objects by issuing the following pazpar2 commands: \r
  31    * 'show', 'stat', 'termlist' and 'bytarget'.\r
  32    *  \r
  33    * Returns a count of the remaining active clients from the most recent search.\r
  34    * \r
  35    * After refreshing the data from pazpar2 the UI components displaying those \r
  36    * data should be re-rendered.\r
  37    * \r
  38    * @return count of activeclients \r
  39    */\r
  40   public String update();\r
  41   \r
  42   /**\r
  43    * Updates the data objects given by a comma separated list of one or more commands - \r
  44    * i.e. "show,state,termlist,bytarget".\r
  45    *  \r
  46    * May not be useful for the UI directly. \r
  47    *  \r
  48    * @param commands Command separated list of pazpar2 commands.\r
  49    * @return count of activeclients \r
  50    * \r
  51    */\r
  52   public String update (String commands);\r
  53             \r
  54   /**\r
  55    * Will retrieve or remove the record with the given recid from memory.\r
  56    * \r
  57    * A pazpar2 'record' command will then be issued. The part of the UI \r
  58    * showing record data should thus be re-rendered.\r
  59    *  \r
  60    * @param recid\r
  61    * @return\r
  62    */\r
  63   public String toggleRecord(String recid);\r
  64     \r
  65   /**\r
  66    * Returns the 'show' data as retrieved from pazpar2 by the most \r
  67    * recent update request\r
  68    * \r
  69    * @return pazpar2 'show' response object\r
  70    */\r
  71   public ShowResponse getShow();\r
  72     \r
  73   /**\r
  74    * Returns the 'stat' data as retrieved from pazpar2 by the most \r
  75    * recent update request\r
  76    * \r
  77    * @return pazpar2 'stat' response object\r
  78    */\r
  79   public StatResponse getStat();\r
  80   \r
  81   /**\r
  82    * Resolves whether the backend has a record with the given recid in memory \r
  83    * \r
  84    * @return true if the bean currently holds the record with recid\r
  85    */  \r
  86   public boolean hasRecord (String recId);\r
  87   \r
  88   /**\r
  89    * Resolves whether the back-end has any records in memory (in 'show') for \r
  90    * display in UI\r
  91    * \r
  92    * @return true if there are records to display\r
  93    */\r
  94   public boolean hasRecords ();\r
  95         \r
  96   /**\r
  97    * Returns a pazpar2 record as retrieved by the most recent 'record'\r
  98    * request \r
  99    * @return record data object\r
 100    */\r
 101   public RecordResponse getRecord();\r
 102   \r
 103   /**\r
 104    * Returns a set of term lists (targets and facets) as retrieved by the \r
 105    * most recent 'termlist' command \r
 106    * @return set of termlists\r
 107    */\r
 108   public TermListsResponse getTermLists ();\r
 109   \r
 110   /**\r
 111    * Returns up to 'count' terms from the facet given by the 'facet' parameter\r
 112    * @param facet  name of the facet\r
 113    * @param count  maximum number of facet terms to return\r
 114    * @return facet term list limited to 'count' terms\r
 115    */\r
 116   public List<TermResponse> getFacetTerms (String facet, int count);\r
 117     \r
 118   /**\r
 119    * Returns all the terms of a given facet - or as many as pazpar2 returns\r
 120    * @param facet name of the facet\r
 121    * @return facet term list\r
 122    */\r
 123   public List<TermResponse> getFacetTerms (String facet);\r
 124   \r
 125   /**\r
 126    * Returns a ByTarget data object as retrieved by the most recent 'bytarget' \r
 127    * request to pazpar2\r
 128    * \r
 129    * @return ByTarget response data object\r
 130    */\r
 131   public ByTarget getByTarget();\r
 132     \r
 133   /**\r
 134    * Initiates a pager object, a component holding the data to draw a sequence\r
 135    * of page numbers to navigate by and mechanisms to navigate with\r
 136    * \r
 137    * @param pageRange number of pages to display in the pager\r
 138    * @return ResultsPager the initiated pager component\r
 139    */\r
 140   public ResultsPager setPager(int pageRange);\r
 141   \r
 142   /**\r
 143    * Gives a component for drawing a pager to navigate by.\r
 144    * @return ResultsPager pager component\r
 145    */\r
 146   public ResultsPager getPager();\r
 147   \r
 148   /**\r
 149    * Returns the current hash key used, as used for internal session state tracking\r
 150    * and potentially for browser history entries as well\r
 151    * \r
 152    * A UI author would not normally be concerned with retrieving this. It's used by the\r
 153    * framework internally\r
 154    *  \r
 155    * @return string that can be used for browsers window.location.hash\r
 156    */\r
 157   public String getCurrentStateKey ();\r
 158       \r
 159   /**\r
 160    * Sets the current state key, i.e. when user clicks back or forward in browser history.\r
 161    * Would normally be automatically handled by the frameworks components.\r
 162    *  \r
 163    * @param key corresponding to browsers hash string\r
 164    */\r
 165   public void setCurrentStateKey(String key);\r
 166   \r
 167   /** \r
 168    * @return true if any errors encountered so far\r
 169    */\r
 170   public boolean hasErrors();\r
 171   \r
 172   /**\r
 173    * \r
 174    * @return true if errors encountered during execution of commands\r
 175    */\r
 176   public boolean hasCommandErrors();\r
 177   \r
 178   /**\r
 179    * \r
 180    * @return true if errors encountered when configuring the service\r
 181    */\r
 182   public boolean hasConfigurationErrors();\r
 183   \r
 184   /**\r
 185    * Returns one (of possibly multiple) errors encountered during execution of commands\r
 186    * Will prefer to show the search errors - if any - as the search command is usually \r
 187    * executed first.  \r
 188    * \r
 189    * @return\r
 190    */\r
 191   public ErrorInterface getCommandError();\r
 192   \r
 193   /**\r
 194    * Returns all errors encountered during configuration of the application, in particular\r
 195    * the Pazpar2 client. \r
 196    * \r
 197    * @return\r
 198    */\r
 199   public List<ErrorInterface> getConfigurationErrors();\r
 200 \r
 201      \r
 202 }\r