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   public void setFilter(String filterExpression);\r
  56   \r
  57   public String getFilter();\r
  58 \r
  59   \r
  60   /**\r
  61    * Adds a single target filter to restrict the current query by, \r
  62    * then executes the current search.\r
  63    * \r
  64    * This is a special case of the general setFilter function, \r
  65    * allowing to associate a descriptive target name with the \r
  66    * filter expression for display in UI. \r
  67    * \r
  68    * @param targetId pazpar2's ID for the target to limit by\r
  69    * @param targetName a descriptive name for the target\r
  70    */\r
  71   public void setSingleTargetFilter (String targetId, String targetName);\r
  72   \r
  73   /**\r
  74    * Removes the current target filter from the search\r
  75    * \r
  76    */\r
  77   public void removeSingleTargetFilter ();\r
  78   \r
  79   /**\r
  80    * \r
  81    * @return The target filter set on the current search command\r
  82    */\r
  83   public SingleTargetFilter getSingleTargetFilter();\r
  84   \r
  85   /**\r
  86    * Resolves if the current search command has a target filter - to\r
  87    * be used by the UI for conditional rendering of target filter info.\r
  88    * \r
  89    * @return true if the current search command is limited by a target \r
  90    * filter\r
  91    */\r
  92   public boolean hasSingleTargetFilter();\r
  93           \r
  94   /**\r
  95    * Will retrieve or remove the record with the given recid from memory.\r
  96    * \r
  97    * A pazpar2 'record' command will then be issued. The part of the UI \r
  98    * showing record data should thus be re-rendered.\r
  99    *  \r
 100    * @param recid\r
 101    * @return\r
 102    */\r
 103   public String toggleRecord(String recid);\r
 104     \r
 105   /**\r
 106    * Returns the 'show' data as retrieved from pazpar2 by the most \r
 107    * recent update request\r
 108    * \r
 109    * @return pazpar2 'show' response object\r
 110    */\r
 111   public ShowResponse getShow();\r
 112     \r
 113   /**\r
 114    * Returns the 'stat' data as retrieved from pazpar2 by the most \r
 115    * recent update request\r
 116    * \r
 117    * @return pazpar2 'stat' response object\r
 118    */\r
 119   public StatResponse getStat();\r
 120   \r
 121   /**\r
 122    * Resolves whether the backend has a record with the given recid in memory \r
 123    * \r
 124    * @return true if the bean currently holds the record with recid\r
 125    */  \r
 126   public boolean hasRecord (String recId);\r
 127   \r
 128   /**\r
 129    * Resolves whether the back-end has any records in memory (in 'show') for \r
 130    * display in UI\r
 131    * \r
 132    * @return true if there are records to display\r
 133    */\r
 134   public boolean hasRecords ();\r
 135         \r
 136   /**\r
 137    * Returns a pazpar2 record as retrieved by the most recent 'record'\r
 138    * request \r
 139    * @return record data object\r
 140    */\r
 141   public RecordResponse getRecord();\r
 142   \r
 143   /**\r
 144    * Returns a set of term lists (targets and facets) as retrieved by the \r
 145    * most recent 'termlist' command \r
 146    * @return set of termlists\r
 147    */\r
 148   public TermListsResponse getTermLists ();\r
 149   \r
 150   /**\r
 151    * Returns up to 'count' terms from the facet given by the 'facet' parameter\r
 152    * @param facet  name of the facet\r
 153    * @param count  maximum number of facet terms to return\r
 154    * @return facet term list limited to 'count' terms\r
 155    */\r
 156   public List<TermResponse> getFacetTerms (String facet, int count);\r
 157     \r
 158   /**\r
 159    * Returns all the terms of a given facet - or as many as pazpar2 returns\r
 160    * @param facet name of the facet\r
 161    * @return facet term list\r
 162    */\r
 163   public List<TermResponse> getFacetTerms (String facet);\r
 164   \r
 165   /**\r
 166    * Returns a ByTarget data object as retrieved by the most recent 'bytarget' \r
 167    * request to pazpar2\r
 168    * \r
 169    * @return ByTarget response data object\r
 170    */\r
 171   public ByTarget getByTarget();\r
 172     \r
 173   /**\r
 174    * Initiates a pager object, a component holding the data to draw a sequence\r
 175    * of page numbers to navigate by and mechanisms to navigate with\r
 176    * \r
 177    * @param pageRange number of pages to display in the pager\r
 178    * @return ResultsPager the initiated pager component\r
 179    */\r
 180   public ResultsPager setPager(int pageRange);\r
 181   \r
 182   /**\r
 183    * Gives a component for drawing a pager to navigate by.\r
 184    * @return ResultsPager pager component\r
 185    */\r
 186   public ResultsPager getPager();\r
 187   \r
 188   /**\r
 189    * Returns the current hash key used, as used for internal session state tracking\r
 190    * and potentially for browser history entries as well\r
 191    * \r
 192    * A UI author would not normally be concerned with retrieving this. It's used by the\r
 193    * framework internally\r
 194    *  \r
 195    * @return string that can be used for browsers window.location.hash\r
 196    */\r
 197   public String getCurrentStateKey ();\r
 198       \r
 199   /**\r
 200    * Sets the current state key, i.e. when user clicks back or forward in browser history.\r
 201    * Would normally be automatically handled by the frameworks components.\r
 202    *  \r
 203    * @param key corresponding to browsers hash string\r
 204    */\r
 205   public void setCurrentStateKey(String key);\r
 206   \r
 207   /** \r
 208    * @return true if any errors encountered so far\r
 209    */\r
 210   public boolean hasErrors();\r
 211   \r
 212   /**\r
 213    * \r
 214    * @return true if errors encountered during execution of commands\r
 215    */\r
 216   public boolean hasCommandErrors();\r
 217   \r
 218   /**\r
 219    * \r
 220    * @return true if errors encountered when configuring the service\r
 221    */\r
 222   public boolean hasConfigurationErrors();\r
 223   \r
 224   /**\r
 225    * Returns one (of possibly multiple) errors encountered during execution of commands\r
 226    * Will prefer to show the search errors - if any - as the search command is usually \r
 227    * executed first.  \r
 228    * \r
 229    * @return\r
 230    */\r
 231   public ErrorInterface getCommandError();\r
 232   \r
 233   /**\r
 234    * Returns all errors encountered during configuration of the application, in particular\r
 235    * the Pazpar2 client. \r
 236    * \r
 237    * @return\r
 238    */\r
 239   public List<ErrorInterface> getConfigurationErrors();\r
 240 \r
 241   void setRecordId(String recId);\r
 242 \r
 243   String getRecordId();\r
 244      \r
 245 }\r