1 files changed, 136 insertions, 0 deletions
diff --git a/src/io/appium/droiddriver/DroidDriver.java b/src/io/appium/droiddriver/DroidDriver.java
new file mode 100644
index 0000000..73c6027
--- /dev/null
+++ b/src/io/appium/droiddriver/DroidDriver.java
@@ -0,0 +1,136 @@
+/*
+ * 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);
+}