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    * 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   public void setFilter(String filterExpression);\r
 102   \r
 103   public String getFilter();\r
 104 \r
 105   \r
 106   /**\r
 107    * Adds a single target filter to restrict the current query by, \r
 108    * then executes the current search.\r
 109    * \r
 110    * This is a special case of the general setFilter function, \r
 111    * allowing to associate a descriptive target name with the \r
 112    * filter expression for display in UI. \r
 113    * \r
 114    * @param targetId pazpar2's ID for the target to limit by\r
 115    * @param targetName a descriptive name for the target\r
 116    */\r
 117   public void setSingleTargetFilter (String targetId, String targetName);\r
 118   \r
 119   /**\r
 120    * Removes the current target filter from the search\r
 121    * \r
 122    */\r
 123   public void removeSingleTargetFilter ();\r
 124   \r
 125   /**\r
 126    * \r
 127    * @return The target filter set on the current search command\r
 128    */\r
 129   public SingleTargetFilter getSingleTargetFilter();\r
 130   \r
 131   /**\r
 132    * Resolves if the current search command has a target filter - to\r
 133    * be used by the UI for conditional rendering of target filter info.\r
 134    * \r
 135    * @return true if the current search command is limited by a target \r
 136    * filter\r
 137    */\r
 138   public boolean hasSingleTargetFilter();\r
 139     \r
 140   /**\r
 141    * Sets the ordering of records (hits) in the 'show' display object\r
 142    */\r
 143   \r
 144   /**\r
 145    * Sets the sort order for results, the updates the 'show' data object\r
 146    * from pazpar2. Set valid sort options in the documentation for pazpar2.\r
 147    * \r
 148    * The parts of the UI that display 'show' data should be rendered following\r
 149    * this request.\r
 150    * \r
 151    * @param sortOption\r
 152    */\r
 153   public void setSort(String sortOption);\r
 154   \r
 155   /**\r
 156    * Retrieves the current sort order for results\r
 157    * @return sort order - i.e. 'relevance'\r
 158    */\r
 159   public String getSort();\r
 160   \r
 161   /**\r
 162    * Sets the number of records that pazpar2 should show at a time. Is \r
 163    * followed by an update of the show data object from pazpar2.  \r
 164    * \r
 165    * To be used by the UI for paging. After setting page size the parts\r
 166    * of the UI that displays 'show' data should be rendered. \r
 167    * \r
 168    * @param perPageOption i.e. 10, default is 20.\r
 169    */\r
 170   public void setPageSize (int perPageOption);\r
 171   \r
 172   /**\r
 173    * Retrieves the currently defined number of items to show at a time\r
 174    * \r
 175    * @return number of result records that will be shown from pazpar2\r
 176    */\r
 177   public int getPageSize();\r
 178   \r
 179   /**\r
 180    * Sets the first record to show - starting at record '0'. After setting\r
 181    * first record number, the 'show' data object will be updated from pazpar2,\r
 182    * and the parts of the UI displaying show data should be re-rendered.\r
 183    * \r
 184    * To be used by the UI for paging.\r
 185    * \r
 186    * @param start first record to show\r
 187    */\r
 188   public void setStart (int start);\r
 189   \r
 190   /**\r
 191    * Retrieves the sequence number of the record that pazpaz2 will return as\r
 192    * the first record in 'show'\r
 193    * \r
 194    * @return sequence number of the first record to be shown (numbering starting at '0')\r
 195    * \r
 196    */\r
 197   public int getStart();\r
 198   \r
 199   /**\r
 200    * Will retrieve or remove the record with the given recid from memory.\r
 201    * \r
 202    * A pazpar2 'record' command will then be issued. The part of the UI \r
 203    * showing record data should thus be re-rendered.\r
 204    *  \r
 205    * @param recid\r
 206    * @return\r
 207    */\r
 208   public String toggleRecord(String recid);\r
 209     \r
 210   /**\r
 211    * Returns the 'show' data as retrieved from pazpar2 by the most \r
 212    * recent update request\r
 213    * \r
 214    * @return pazpar2 'show' response object\r
 215    */\r
 216   public ShowResponse getShow();\r
 217     \r
 218   /**\r
 219    * Returns the 'stat' data as retrieved from pazpar2 by the most \r
 220    * recent update request\r
 221    * \r
 222    * @return pazpar2 'stat' response object\r
 223    */\r
 224   public StatResponse getStat();\r
 225   \r
 226   /**\r
 227    * Resolves whether the backend has a record with the given recid in memory \r
 228    * \r
 229    * @return true if the bean currently holds the record with recid\r
 230    */  \r
 231   public boolean hasRecord (String recId);\r
 232   \r
 233   /**\r
 234    * Resolves whether the back-end has any records in memory (in 'show') for \r
 235    * display in UI\r
 236    * \r
 237    * @return true if there are records to display\r
 238    */\r
 239   public boolean hasRecords ();\r
 240         \r
 241   /**\r
 242    * Returns a pazpar2 record as retrieved by the most recent 'record'\r
 243    * request \r
 244    * @return record data object\r
 245    */\r
 246   public RecordResponse getRecord();\r
 247   \r
 248   /**\r
 249    * Returns a set of term lists (targets and facets) as retrieved by the \r
 250    * most recent 'termlist' command \r
 251    * @return set of termlists\r
 252    */\r
 253   public TermListsResponse getTermLists ();\r
 254   \r
 255   /**\r
 256    * Returns up to 'count' terms from the facet given by the 'facet' parameter\r
 257    * @param facet  name of the facet\r
 258    * @param count  maximum number of facet terms to return\r
 259    * @return facet term list limited to 'count' terms\r
 260    */\r
 261   public List<TermResponse> getFacetTerms (String facet, int count);\r
 262     \r
 263   /**\r
 264    * Returns all the terms of a given facet - or as many as pazpar2 returns\r
 265    * @param facet name of the facet\r
 266    * @return facet term list\r
 267    */\r
 268   public List<TermResponse> getFacetTerms (String facet);\r
 269   \r
 270   /**\r
 271    * Returns a ByTarget data object as retrieved by the most recent 'bytarget' \r
 272    * request to pazpar2\r
 273    * \r
 274    * @return ByTarget response data object\r
 275    */\r
 276   public ByTarget getByTarget();\r
 277     \r
 278   /**\r
 279    * Initiates a pager object, a component holding the data to draw a sequence\r
 280    * of page numbers to navigate by and mechanisms to navigate with\r
 281    * \r
 282    * @param pageRange number of pages to display in the pager\r
 283    * @return ResultsPager the initiated pager component\r
 284    */\r
 285   public ResultsPager setPager(int pageRange);\r
 286   \r
 287   /**\r
 288    * Gives a component for drawing a pager to navigate by.\r
 289    * @return ResultsPager pager component\r
 290    */\r
 291   public ResultsPager getPager();\r
 292   \r
 293   /**\r
 294    * Returns the current hash key used, as used for internal session state tracking\r
 295    * and potentially for browser history entries as well\r
 296    * \r
 297    * A UI author would not normally be concerned with retrieving this. It's used by the\r
 298    * framework internally\r
 299    *  \r
 300    * @return string that can be used for browsers window.location.hash\r
 301    */\r
 302   public String getCurrentStateKey ();\r
 303       \r
 304   /**\r
 305    * Sets the current state key, i.e. when user clicks back or forward in browser history.\r
 306    * Would normally be automatically handled by the frameworks components.\r
 307    *  \r
 308    * @param key corresponding to browsers hash string\r
 309    */\r
 310   public void setCurrentStateKey(String key);\r
 311   \r
 312   /** \r
 313    * @return true if any errors encountered so far\r
 314    */\r
 315   public boolean hasErrors();\r
 316   \r
 317   /**\r
 318    * \r
 319    * @return true if errors encountered during execution of commands\r
 320    */\r
 321   public boolean hasCommandErrors();\r
 322   \r
 323   /**\r
 324    * \r
 325    * @return true if errors encountered when configuring the service\r
 326    */\r
 327   public boolean hasConfigurationErrors();\r
 328   \r
 329   /**\r
 330    * Returns one (of possibly multiple) errors encountered during execution of commands\r
 331    * Will prefer to show the search errors - if any - as the search command is usually \r
 332    * executed first.  \r
 333    * \r
 334    * @return\r
 335    */\r
 336   public ErrorInterface getCommandError();\r
 337   \r
 338   /**\r
 339    * Returns all errors encountered during configuration of the application, in particular\r
 340    * the Pazpar2 client. \r
 341    * \r
 342    * @return\r
 343    */\r
 344   public List<ErrorInterface> getConfigurationErrors();\r
 345 \r
 346   void setRecordId(String recId);\r
 347 \r
 348   String getRecordId();\r
 349      \r
 350 }\r