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.pazpar2.TargetFilter;\r
   8 import com.indexdata.pz2utils4jsf.pazpar2.data.ApplicationError;\r
   9 import com.indexdata.pz2utils4jsf.pazpar2.data.ByTarget;\r
  10 import com.indexdata.pz2utils4jsf.pazpar2.data.RecordResponse;\r
  11 import com.indexdata.pz2utils4jsf.pazpar2.data.ShowResponse;\r
  12 import com.indexdata.pz2utils4jsf.pazpar2.data.StatResponse;\r
  13 import com.indexdata.pz2utils4jsf.pazpar2.data.TermListsResponse;\r
  14 import com.indexdata.pz2utils4jsf.pazpar2.data.TermResponse;\r
  15 \r
  16 public interface Pz2Interface extends Serializable {\r
  17 \r
  18   /**\r
  19    * Executes a Pazpar2 search using the given query string\r
  20    * \r
  21    * @param query\r
  22    */\r
  23   public void doSearch(String query);\r
  24   \r
  25   /**\r
  26    * Executes a Pazpar2 search using the current query \r
  27    */\r
  28   public void doSearch();\r
  29   \r
  30   /**\r
  31    * Updates display data objects by issuing the following pazpar2 commands: \r
  32    * 'show', 'stat', 'termlist' and 'bytarget'.\r
  33    *  \r
  34    * Returns a count of the remaining active clients from the most recent search.\r
  35    * \r
  36    * After refreshing the data from pazpar2 the UI components displaying those \r
  37    * data should be re-rendered.\r
  38    * \r
  39    * @return count of activeclients \r
  40    */\r
  41   public String update();\r
  42   \r
  43   /**\r
  44    * Updates the data objects given by a comma separated list of one or more commands - \r
  45    * i.e. "show,state,termlist,bytarget".\r
  46    *  \r
  47    * May not be useful for the UI directly. \r
  48    *  \r
  49    * @param commands Command separated list of pazpar2 commands.\r
  50    * @return count of activeclients \r
  51    * \r
  52    */\r
  53   public String update (String commands);\r
  54   \r
  55   /**\r
  56    * Sets a query to used by the next search command\r
  57    * \r
  58    * @param query a query on pazpar2 query syntax\r
  59    * \r
  60    */\r
  61   public void setQuery (String query);\r
  62   \r
  63   /**\r
  64    * Gets the current query  \r
  65    * @return a pazpar2 query string\r
  66    */\r
  67   public String getQuery ();\r
  68   \r
  69   /**\r
  70    * Sets a facet to limit the current query by,\r
  71    * then executes the search \r
  72    * \r
  73    * @param facetKey  i.e.  'au' for author\r
  74    * @param term  i.e. 'Dickens, Charles'\r
  75    */\r
  76   public void setFacet(String facetKey, String term);\r
  77   \r
  78   /**\r
  79    * Removes a facet set by setFacet(...), then executes\r
  80    * the search.\r
  81    * \r
  82    * Will not remove facets set by setFacetOnQuery(...)\r
  83    *  \r
  84    * @param facetKey i.e. 'au' for author\r
  85    * @param term i.e. 'Dickens, Charles'\r
  86    */\r
  87   public void removeFacet (String facetKey, String term);\r
  88   \r
  89   /**\r
  90    * Sets a facet to limit the current query by. The \r
  91    * facet is appended to the query string itself (rather\r
  92    * as a separately managed entity. It will thus appear\r
  93    * in a query field as retrieved by getQuery(). It will\r
  94    * not be removed by removeFacet(...)\r
  95    * \r
  96    * @param facetKey  i.e. 'au' for author\r
  97    * @param term i.e. 'Dickens, Charles'\r
  98    */\r
  99   public void setFacetOnQuery(String facetKey, String term);\r
 100   \r
 101   /**\r
 102    * Adds a target filter to limit the current query by, then\r
 103    * executes the current search.\r
 104    * \r
 105    * @param targetId pazpar2's ID for the target to limit by\r
 106    * @param targetName a descriptive name for the target\r
 107    */\r
 108   public void setTargetFilter (String targetId, String targetName);\r
 109   \r
 110   /**\r
 111    * Removes the current target filter from the search\r
 112    * \r
 113    */\r
 114   public void removeTargetFilter ();\r
 115   \r
 116   /**\r
 117    * \r
 118    * @return The target filter set on the current search command\r
 119    */\r
 120   public TargetFilter getTargetFilter();\r
 121   \r
 122   /**\r
 123    * Resolves if the current search command has a target filter - to\r
 124    * be used by the UI for conditional rendering of target filter info.\r
 125    * \r
 126    * @return true if the current search command is limited by a target \r
 127    * filter\r
 128    */\r
 129   public boolean hasTargetFilter();\r
 130   \r
 131   /**\r
 132    * Sets the ordering of records (hits) in the 'show' display object\r
 133    */\r
 134   \r
 135   /**\r
 136    * Sets the sort order for results, the updates the 'show' data object\r
 137    * from pazpar2. Set valid sort options in the documentation for pazpar2.\r
 138    * \r
 139    * The parts of the UI that display 'show' data should be rendered following\r
 140    * this request.\r
 141    * \r
 142    * @param sortOption\r
 143    */\r
 144   public void setSort(String sortOption);\r
 145   \r
 146   /**\r
 147    * Retrieves the current sort order for results\r
 148    * @return sort order - i.e. 'relevance'\r
 149    */\r
 150   public String getSort();\r
 151   \r
 152   /**\r
 153    * Sets the number of records that pazpar2 should show at a time. Is \r
 154    * followed by an update of the show data object from pazpar2.  \r
 155    * \r
 156    * To be used by the UI for paging. After setting page size the parts\r
 157    * of the UI that displays 'show' data should be rendered. \r
 158    * \r
 159    * @param perPageOption i.e. 10, default is 20.\r
 160    */\r
 161   public void setPageSize (int perPageOption);\r
 162   \r
 163   /**\r
 164    * Retrieves the currently defined number of items to show at a time\r
 165    * \r
 166    * @return number of result records that will be shown from pazpar2\r
 167    */\r
 168   public int getPageSize();\r
 169   \r
 170   /**\r
 171    * Sets the first record to show - starting at record '0'. After setting\r
 172    * first record number, the 'show' data object will be updated from pazpar2,\r
 173    * and the parts of the UI displaying show data should be re-rendered.\r
 174    * \r
 175    * To be used by the UI for paging.\r
 176    * \r
 177    * @param start first record to show\r
 178    */\r
 179   public void setStart (int start);\r
 180   \r
 181   /**\r
 182    * Retrieves the sequence number of the record that pazpaz2 will return as\r
 183    * the first record in 'show'\r
 184    * \r
 185    * @return sequence number of the first record to be shown (numbering starting at '0')\r
 186    * \r
 187    */\r
 188   public int getStart();\r
 189   \r
 190   /**\r
 191    * Will retrieve or remove the record with the given recid from memory.\r
 192    * \r
 193    * A pazpar2 'record' command will then be issued. The part of the UI \r
 194    * showing record data should thus be re-rendered.\r
 195    *  \r
 196    * @param recid\r
 197    * @return\r
 198    */\r
 199   public String toggleRecord(String recid);\r
 200     \r
 201   /**\r
 202    * Returns the 'show' data as retrieved from pazpar2 by the most \r
 203    * recent update request\r
 204    * \r
 205    * @return pazpar2 'show' response object\r
 206    */\r
 207   public ShowResponse getShow();\r
 208   \r
 209   /**\r
 210    * Returns the 'stat' data as retrieved from pazpar2 by the most \r
 211    * recent update request\r
 212    * \r
 213    * @return pazpar2 'stat' response object\r
 214    */\r
 215   public StatResponse getStat();\r
 216   \r
 217   /**\r
 218    * Resolves whether the backend has a record with the given recid in memory \r
 219    * \r
 220    * @return true if the bean currently holds the record with recid\r
 221    */  \r
 222   public boolean hasRecord (String recId);\r
 223   \r
 224   /**\r
 225    * Resolves whether the back-end has any records in memory (in 'show') for \r
 226    * display in UI\r
 227    * \r
 228    * @return true if there are records to display\r
 229    */\r
 230   public boolean hasRecords ();\r
 231         \r
 232   /**\r
 233    * Returns a pazpar2 record as retrieved by the most recent 'record'\r
 234    * request \r
 235    * @return record data object\r
 236    */\r
 237   public RecordResponse getRecord();\r
 238   \r
 239   /**\r
 240    * Returns a set of term lists (targets and facets) as retrieved by the \r
 241    * most recent 'termlist' command \r
 242    * @return set of termlists\r
 243    */\r
 244   public TermListsResponse getTermLists ();\r
 245   \r
 246   /**\r
 247    * Returns up to 'count' terms from the facet given by the 'facet' parameter\r
 248    * @param facet  name of the facet\r
 249    * @param count  maximum number of facet terms to return\r
 250    * @return facet term list limited to 'count' terms\r
 251    */\r
 252   public List<TermResponse> getFacetTerms (String facet, int count);\r
 253     \r
 254   /**\r
 255    * Returns all the terms of a given facet - or as many as pazpar2 returns\r
 256    * @param facet name of the facet\r
 257    * @return facet term list\r
 258    */\r
 259   public List<TermResponse> getFacetTerms (String facet);\r
 260   \r
 261   /**\r
 262    * Returns a ByTarget data object as retrieved by the most recent 'bytarget' \r
 263    * request to pazpar2\r
 264    * \r
 265    * @return ByTarget response data object\r
 266    */\r
 267   public ByTarget getByTarget();\r
 268     \r
 269   /**\r
 270    * Initiates a pager object, a component holding the data to draw a sequence\r
 271    * of page numbers to navigate by and mechanisms to navigate with\r
 272    * \r
 273    * @param pageRange number of pages to display in the pager\r
 274    * @return ResultsPager the initiated pager component\r
 275    */\r
 276   public ResultsPager setPager(int pageRange);\r
 277   \r
 278   /**\r
 279    * Gives a component for drawing a pager to navigate by.\r
 280    * @return ResultsPager pager component\r
 281    */\r
 282   public ResultsPager getPager();\r
 283   \r
 284   /**\r
 285    * Returns the current hash key used, as used for internal session state tracking\r
 286    * and potentially for browser history entries as well\r
 287    * \r
 288    * A UI author would not normally be concerned with retrieving this. It's used by the\r
 289    * framework internally\r
 290    *  \r
 291    * @return string that can be used for browsers window.location.hash\r
 292    */\r
 293   public String getCurrentStateKey ();\r
 294       \r
 295   /**\r
 296    * Sets the current state key, i.e. when user clicks back or forward in browser history.\r
 297    * Would normally be automatically handled by the frameworks components.\r
 298    *  \r
 299    * @param key corresponding to browsers hash string\r
 300    */\r
 301   public void setCurrentStateKey(String key);\r
 302   \r
 303   public boolean hasErrors();\r
 304       \r
 305   public ApplicationError getOneError();\r
 306    \r
 307 }\r