interface SearchApiDataSourceControllerInterface in Search API 7

Interface for all data source controllers for Search API indexes.

Data source controllers encapsulate all operations specific to an item type. They are used for loading items, extracting item data, keeping track of the item status, etc.

Modules providing implementations of this interface that use a different way (either different table or different method altogether) of keeping track of indexed/dirty items than SearchApiAbstractDataSourceController should be aware that indexes' numerical IDs can change due to feature reverts. It is therefore recommended to use search_api_index_update_datasource(), or similar code, in a hook_search_api_index_update() implementation.

Hierarchy

interface \SearchApiDataSourceControllerInterface

Expanded class hierarchy of SearchApiDataSourceControllerInterface

All classes that implement SearchApiDataSourceControllerInterface

File

includes/datasource.inc, line 22: Contains the SearchApiDataSourceControllerInterface as well as a default base class.

View source

interface SearchApiDataSourceControllerInterface {

  /**
   * Constructs an SearchApiDataSourceControllerInterface object.
   *
   * @param string $type
   *   The item type for which this controller is created.
   */
  public function __construct($type);

  /**
   * Returns information on the ID field for this controller's type.
   *
   * @return array
   *   An associative array containing the following keys:
   *   - key: The property key for the ID field, as used in the item wrapper.
   *   - type: The type of the ID field. Has to be one of the types from
   *     search_api_field_types(). List types ("list<*>") are not allowed.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function getIdFieldInfo();

  /**
   * Loads items of the type of this data source controller.
   *
   * @param array $ids
   *   The IDs of the items to load.
   *
   * @return array
   *   The loaded items, keyed by ID.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function loadItems(array $ids);

  /**
   * Creates a metadata wrapper for this datasource controller's type.
   *
   * @param mixed $item
   *   Unless NULL, an item of the item type for this controller to be wrapped.
   * @param array $info
   *   Optionally, additional information that should be used for creating the
   *   wrapper. Uses the same format as entity_metadata_wrapper().
   *
   * @return EntityMetadataWrapper
   *   A wrapper for the item type of this data source controller, according to
   *   the info array, and optionally loaded with the given data.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   *
   * @see entity_metadata_wrapper()
   */
  public function getMetadataWrapper($item = NULL, array $info = array());

  /**
   * Retrieves the unique ID of an item.
   *
   * @param mixed $item
   *   An item of this controller's type.
   *
   * @return mixed
   *   Either the unique ID of the item, or NULL if none is available.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function getItemId($item);

  /**
   * Retrieves a human-readable label for an item.
   *
   * @param mixed $item
   *   An item of this controller's type.
   *
   * @return string|null
   *   Either a human-readable label for the item, or NULL if none is available.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function getItemLabel($item);

  /**
   * Retrieves a URL at which the item can be viewed on the web.
   *
   * @param mixed $item
   *   An item of this controller's type.
   *
   * @return array|null
   *   Either an array containing the 'path' and 'options' keys used to build
   *   the URL of the item, and matching the signature of url(), or NULL if the
   *   item has no URL of its own.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function getItemUrl($item);

  /**
   * Initializes tracking of the index status of items for the given indexes.
   *
   * All currently known items of this data source's type should be inserted
   * into the tracking table for the given indexes, with status "changed". If
   * items were already present, these should also be set to "changed" and not
   * be inserted again.
   *
   * @param SearchApiIndex[] $indexes
   *   The SearchApiIndex objects for which item tracking should be initialized.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function startTracking(array $indexes);

  /**
   * Stops tracking of the index status of items for the given indexes.
   *
   * The tracking tables of the given indexes should be completely cleared.
   *
   * @param SearchApiIndex[] $indexes
   *   The SearchApiIndex objects for which item tracking should be stopped.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function stopTracking(array $indexes);

  /**
   * Starts tracking the index status for the given items on the given indexes.
   *
   * @param array $item_ids
   *   The IDs of new items to track.
   * @param SearchApiIndex[] $indexes
   *   The indexes for which items should be tracked.
   *
   * @return SearchApiIndex[]|null
   *   All indexes for which any items were added; or NULL if items were added
   *   for all of them.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function trackItemInsert(array $item_ids, array $indexes);

  /**
   * Sets the tracking status of the given items to "changed"/"dirty".
   *
   * Unless $dequeue is set to TRUE, this operation is ignored for items whose
   * status is not "indexed".
   *
   * @param array|false $item_ids
   *   Either an array with the IDs of the changed items. Or FALSE to mark all
   *   items as changed for the given indexes.
   * @param SearchApiIndex[] $indexes
   *   The indexes for which the change should be tracked.
   * @param bool $dequeue
   *   (deprecated) If set to TRUE, also change the status of queued items.
   *   The concept of queued items will be removed in the Drupal 8 version of
   *   this module.
   *
   * @return SearchApiIndex[]|null
   *   All indexes for which any items were updated; or NULL if items were
   *   updated for all of them.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function trackItemChange($item_ids, array $indexes, $dequeue = FALSE);

  /**
   * Sets the tracking status of the given items to "queued".
   *
   * Queued items are not marked as "dirty" even when they are changed, and they
   * are not returned by the getChangedItems() method.
   *
   * @param array|false $item_ids
   *   Either an array with the IDs of the queued items. Or FALSE to mark all
   *   items as queued for the given indexes.
   * @param SearchApiIndex $index
   *   The index for which the items were queued.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   *
   * @deprecated
   *   As of Search API 1.10, the cron queue is not used for indexing anymore,
   *   therefore this method has become useless. It will be removed in the
   *   Drupal 8 version of this module.
   */
  public function trackItemQueued($item_ids, SearchApiIndex $index);

  /**
   * Sets the tracking status of the given items to "indexed".
   *
   * @param array $item_ids
   *   The IDs of the indexed items.
   * @param SearchApiIndex $index
   *   The index on which the items were indexed.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function trackItemIndexed(array $item_ids, SearchApiIndex $index);

  /**
   * Stops tracking the index status for the given items on the given indexes.
   *
   * @param array $item_ids
   *   The IDs of the removed items.
   * @param SearchApiIndex[] $indexes
   *   The indexes for which the deletions should be tracked.
   *
   * @return SearchApiIndex[]|null
   *   All indexes for which any items were deleted; or NULL if items were
   *   deleted for all of them.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function trackItemDelete(array $item_ids, array $indexes);

  /**
   * Retrieves a list of items that need to be indexed.
   *
   * If possible, completely unindexed items should be returned before items
   * that were indexed but later changed. Also, items that were changed longer
   * ago should be favored.
   *
   * @param SearchApiIndex $index
   *   The index for which changed items should be returned.
   * @param int $limit
   *   The maximum number of items to return. Negative values mean "unlimited".
   *
   * @return array
   *   The IDs of items that need to be indexed for the given index.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function getChangedItems(SearchApiIndex $index, $limit = -1);

  /**
   * Retrieves information on how many items have been indexed for a certain index.
   *
   * @param SearchApiIndex $index
   *   The index whose index status should be returned.
   *
   * @return array
   *   An associative array containing two keys (in this order):
   *   - indexed: The number of items already indexed in their latest version.
   *   - total: The total number of items that have to be indexed for this
   *     index.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function getIndexStatus(SearchApiIndex $index);

  /**
   * Retrieves the entity type of items from this datasource.
   *
   * @return string|null
   *   An entity type string if the items provided by this datasource are
   *   entities; NULL otherwise.
   *
   * @throws SearchApiDataSourceException
   *   If any error state was encountered.
   */
  public function getEntityType();

  /**
   * Form constructor for configuring the datasource for a given index.
   *
   * @param array $form
   *   The form returned by configurationForm().
   * @param array $form_state
   *   The form state. $form_state['index'] will contain the edited index. If
   *   this key is empty, then a new index is being created. In case of an edit,
   *   $form_state['index']->options['datasource'] contains the previous
   *   settings for the datasource.
   *
   * @return array|false
   *   A form array for configuring this callback, or FALSE if no configuration
   *   is possible.
   */
  public function configurationForm(array $form, array &$form_state);

  /**
   * Validation callback for the form returned by configurationForm().
   *
   * This method will only be called if that form was non-empty.
   *
   * @param array $form
   *   The form returned by configurationForm().
   * @param array $values
   *   The part of the $form_state['values'] array corresponding to this form.
   * @param array $form_state
   *   The complete form state.
   */
  public function configurationFormValidate(array $form, array &$values, array &$form_state);

  /**
   * Submit callback for the form returned by configurationForm().
   *
   * This method will only be called if that form was non-empty.
   *
   * Any necessary changes to the submitted values should be made, afterwards
   * they will automatically be stored as the index's "datasource" options. The
   * method can also be used by the datasource controller to react to the
   * possible change in its settings.
   *
   * @param array $form
   *   The form returned by configurationForm().
   * @param array $values
   *   The part of the $form_state['values'] array corresponding to this form.
   * @param array $form_state
   *   The complete form state.
   */
  public function configurationFormSubmit(array $form, array &$values, array &$form_state);

  /**
   * Returns a summary of an index's current datasource configuration.
   *
   * @param SearchApiIndex $index
   *   The index whose datasource configuration should be summarized.
   *
   * @return string|null
   *   A translated string describing the index's current datasource
   *   configuration. Or NULL, if there is no configuration (or no description
   *   is available).
   */
  public function getConfigurationSummary(SearchApiIndex $index);

}

Members

Name	Modifiers	Type	Description	Overrides
SearchApiDataSourceControllerInterface::configurationForm	public	function	Form constructor for configuring the datasource for a given index.	1
SearchApiDataSourceControllerInterface::configurationFormSubmit	public	function	Submit callback for the form returned by configurationForm().	1
SearchApiDataSourceControllerInterface::configurationFormValidate	public	function	Validation callback for the form returned by configurationForm().	1
SearchApiDataSourceControllerInterface::getChangedItems	public	function	Retrieves a list of items that need to be indexed.	1
SearchApiDataSourceControllerInterface::getConfigurationSummary	public	function	Returns a summary of an index's current datasource configuration.	1
SearchApiDataSourceControllerInterface::getEntityType	public	function	Retrieves the entity type of items from this datasource.	1
SearchApiDataSourceControllerInterface::getIdFieldInfo	public	function	Returns information on the ID field for this controller's type.	3
SearchApiDataSourceControllerInterface::getIndexStatus	public	function	Retrieves information on how many items have been indexed for a certain index.	1
SearchApiDataSourceControllerInterface::getItemId	public	function	Retrieves the unique ID of an item.	1
SearchApiDataSourceControllerInterface::getItemLabel	public	function	Retrieves a human-readable label for an item.	1
SearchApiDataSourceControllerInterface::getItemUrl	public	function	Retrieves a URL at which the item can be viewed on the web.	1
SearchApiDataSourceControllerInterface::getMetadataWrapper	public	function	Creates a metadata wrapper for this datasource controller's type.	1
SearchApiDataSourceControllerInterface::loadItems	public	function	Loads items of the type of this data source controller.	3
SearchApiDataSourceControllerInterface::startTracking	public	function	Initializes tracking of the index status of items for the given indexes.	1
SearchApiDataSourceControllerInterface::stopTracking	public	function	Stops tracking of the index status of items for the given indexes.	1
SearchApiDataSourceControllerInterface::trackItemChange	public	function	Sets the tracking status of the given items to "changed"/"dirty".	1
SearchApiDataSourceControllerInterface::trackItemDelete	public	function	Stops tracking the index status for the given items on the given indexes.	1
SearchApiDataSourceControllerInterface::trackItemIndexed	public	function	Sets the tracking status of the given items to "indexed".	1
SearchApiDataSourceControllerInterface::trackItemInsert	public	function	Starts tracking the index status for the given items on the given indexes.	1
SearchApiDataSourceControllerInterface::trackItemQueued Deprecated	public	function	Sets the tracking status of the given items to "queued".	1
SearchApiDataSourceControllerInterface::__construct	public	function	Constructs an SearchApiDataSourceControllerInterface object.	1

You are here

interface SearchApiDataSourceControllerInterface in Search API 7

Hierarchy

File

Members

API Navigation