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