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

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