package com.k_int.sru.search_widget;

import java.util.List;
import java.util.Map;

import javax.swing.Action;

import com.k_int.sru.search_widget.dto.SRWResultDTO;

public interface SRUSearchWidget {


  /**
   * Used to retrieve the query used in the last search execution. 
   * 
   * @return The query string.
   */
  public String getQuery();


  /**
   * This method is used to auto-complete the widgets query field with the given {@link String}.
   * The parameter must be fully formed (I.E. a {@link String} returned by getQuery()) or the search operation will fail.
   * The parameter should be url encoded in UTF-8.
   *
   * @param query The fully formed query to use.
   */ 
  public void setQuery(String query);
  

  /**
   * This method is used to pre-populate the widget with the values in the {@link Map}.
   *
   * @param query_key_and_values The {@link List} set of values for the single key to use.
   */
  public void setQueryValues(Map<String, String> query_key_and_values);
  

  /**
   * Used to retrieve the results of the last search that the user has flagged as selected.
   *
   * @return The {@link List} of results.
   */  
  public List<SRWResultDTO> getSelectedResults();


  /**
   * Adds a list of actions to the default screen. 
   * This creates a {@link javax.swing.JButton} with the associated action for each item in the {@link List}
   *
   * @param The {@link List} of actions to be added.
   */
  public void addAction(List<Action> actions);


  /**
   * Adds a list of actions to the specified screen.
   * This creates a {@link javax.swing.JButton} with the associated action for each item in the {@link List}
   *
   * @TODO replace tab name with enum? at least add method to get the tabs back!
   *
   * @param actions The {@link List} of actions to be added.
   * @param tab_name The tab name {@link String} to add the actions to.
   */
  public void addAction(List<Action> actions, String tab_name);

  
  /**
   * Saves the ui preferences (width and height) back to the filesystem. 
   */
  public void savePreferences();


  /**
   * Sets a new {@link WidgetConfig} configuration object to be used by the widget.
   *
   * @param config The new {@link WidgetConfig} to use.
   */
  public void setConfig(WidgetConfig config);


  /**
   * Returns the current {@linkWidgetConfig} configuration object that is in use by the widget.
   * This is created by default on widget construction.
   *
   * @return The {@link WidgetConfig} currently in use by the widget.
   */
  public WidgetConfig getConfig();


  /**
   * Stops the execution of the currently running search.
   */
  public void stopSearch();


  /**
   * Creates a {@link Searcher} object, search thread and runs the new search.
   * 
   * @param start_rec The index of the record to start from (typically defaults to 1)
   * @param clear Whether to clear the existing resultset if it exists and start a new collection of result dtos.
   */
  public void startSearch(Integer start_rec, boolean clear);
}