/*
 * Copyright (C) 2013 DroidDriver committers
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.appium.droiddriver;

import io.appium.droiddriver.exceptions.ElementNotFoundException;
import io.appium.droiddriver.exceptions.TimeoutException;
import io.appium.droiddriver.finders.Finder;

/**
 * The entry interface for using droiddriver.
 */
public interface DroidDriver {
  /**
   * Returns whether a matching element exists without polling. Use this if the
   * UI is not in the progress of updating.
   */
  boolean has(Finder finder);

  /**
   * Returns whether a matching element appears within {@code timeoutMillis}.
   * Use this only if you have no way to determine the content of current page.
   * There are very few occasions using this is justified. For instance, you are
   * looking for UiElements in a scrollable view, whose content varies based on
   * the scroll position. Refrain from using this method in these cases:
   * <ul>
   * <li>You know one of a set of UiElements will show, but are not sure which
   * one. Use this instead:
   *
   * <pre>
   * UiElement el = driver.on(By.anyOf(finder1, finder2, ...));
   * // UI is stable now, find which one is returned
   * if (finder1.matches(el)) ...
   * </pre>
   *
   * </li>
   * <li>You know the UiElement will appear, and want to optimize the speed by
   * using a smaller timeout than the default timeout. It's not worth it -- on
   * and checkExists return as soon as the finder is found. If it is not found,
   * that's a test failure and should be rare.</li>
   * </ul>
   */
  boolean has(Finder finder, long timeoutMillis);

  /**
   * Returns the first {@link UiElement} found using the given finder. This
   * method will poll until a match is found, or the default timeout is reached.
   *
   * @param finder The matching mechanism
   * @return The first matching element
   * @throws TimeoutException If no matching elements are found within the
   *         allowed time
   */
  UiElement on(Finder finder);

  /**
   * Returns the first {@link UiElement} found using the given finder without
   * polling and without {@link #refreshUiElementTree}. This method is useful in
   * {@link Poller.PollingListener#onPolling}. In other situations polling is
   * desired, and {@link #on} is more appropriate.
   *
   * @param finder The matching mechanism
   * @return The first matching element
   * @throws ElementNotFoundException If no matching elements are found
   */
  UiElement find(Finder finder);

  /**
   * Refreshes the UiElement tree. All methods in this interface that take a
   * Finder parameter call this method, unless noted otherwise.
   */
  void refreshUiElementTree();

  /**
   * Polls until a {@link UiElement} is found using the given finder, or the
   * default timeout is reached. This behaves the same as {@link #on} except
   * that it does not return the {@link UiElement}.
   *
   * @param finder The matching mechanism
   * @throws TimeoutException If matching element does not appear within the
   *         default timeout
   */
  void checkExists(Finder finder);

  /**
   * Polls until the {@link UiElement} found using the given finder is gone, or
   * the default timeout is reached.
   *
   * @param finder The matching mechanism
   * @throws TimeoutException If matching element is not gone within the default
   *         timeout
   */
  void checkGone(Finder finder);

  /**
   * Returns the {@link Poller}.
   */
  Poller getPoller();

  /**
   * Sets the {@link Poller}.
   */
  void setPoller(Poller poller);

  /**
   * Returns a {@link UiDevice} for device-wide interaction.
   */
  UiDevice getUiDevice();

  /**
   * Dumps the UiElement tree to a file to help debug. The tree is based on the
   * last used root UiElement if it exists, otherwise
   * {@link #refreshUiElementTree} is called.
   * <p>
   * The dump may contain invisible UiElements that are not used in the finding
   * algorithm.
   * </p>
   *
   * @param path the path of file to save the tree
   * @return whether the dumping succeeded
   */
  boolean dumpUiElementTree(String path);
}