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