Update the documentation on push/pull file helpers (appium#906)

Author: Mykola Mokhnach

src/main/java/io/appium/java_client/InteractsWithFiles.java

@@ -29,11 +29,21 @@ public interface InteractsWithFiles extends ExecutesMethod {
 
  /**
  * Pull a file from the simulator/device.
+ * On iOS the server should have ifuse
+ * libraries installed and configured properly for this feature to work
+ * on real devices.
+ * On Android the application under test should be
+ * built with debuggable flag enabled in order to get access to its container
+ * on the internal file system.
  *
- * @param remotePath On Android and iOS, this is either the path to the file
- * (relative to the root of the app's file system). On iOS only,
- * if path starts with /AppName.app, which will be replaced with
- * the application's .app directory
+ * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page6</a>
+ * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
+ * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
+ *
+ * @param remotePath If the path starts with <em>@applicationId/</em>/ prefix, then the file
+ * will be pulled from the root of the corresponding application container.
+ * Otherwise the root folder is considered as / on Android and
+ * on iOS it is a media folder root (real devices only).
  * @return A byte array of Base64 encoded data.
  */
  default byte[] pullFile(String remotePath) {
@@ -44,15 +54,23 @@ default byte[] pullFile(String remotePath) {
  }
 
  /**
- * Pull a folder from the simulator/device. Does not work on iOS Real
- * Devices, but works on simulators
+ * Pull a folder content from the simulator/device.
+ * On iOS the server should have ifuse
+ * libraries installed and configured properly for this feature to work
+ * on real devices.
+ * On Android the application under test should be
+ * built with debuggable flag enabled in order to get access to its container
+ * on the internal file system.
+ *
+ * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page6</a>
+ * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
+ * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
  *
- * @param remotePath On Android and iOS, this is either the path to the file
- * (relative to the root of the app's file system). On iOS only,
- * if path starts with /AppName.app, which will be replaced with
- * the application's .app directory
- * @return A byte array of Base64 encoded data, representing a ZIP ARCHIVE
- * of the contents of the requested folder.
+ * @param remotePath If the path starts with <em>@applicationId/</em> prefix, then the folder
+ * will be pulled from the root of the corresponding application container.
+ * Otherwise the root folder is considered as / on Android and
+ * on iOS it is a media folder root (real devices only).
+ * @return A byte array of Base64 encoded zip archive data.
  */
  default byte[] pullFolder(String remotePath) {
  Response response = execute(PULL_FOLDER, ImmutableMap.of("path", remotePath));

src/main/java/io/appium/java_client/android/PushesFiles.java

@@ -32,18 +32,32 @@ public interface PushesFiles extends InteractsWithFiles, ExecutesMethod {
 
  /**
  * Saves base64 encoded data as a file on the remote mobile device.
+ * The application under test should be
+ * built with debuggable flag enabled in order to get access to its container
+ * on the internal file system.
+ *
+ * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
  *
  * @param remotePath Path to file to write data to on remote device
+ * If the path starts with <em>@applicationId/</em> prefix, then the file
+ * will be pushed to the root of the corresponding application container.
  * @param base64Data Base64 encoded byte array of data to write to remote device
  */
  default void pushFile(String remotePath, byte[] base64Data) {
  CommandExecutionHelper.execute(this, pushFileCommand(remotePath, base64Data));
  }
 
  /**
- * Saves given file as a file on the remote mobile device.
+ * Saves the given file to the remote mobile device.
+ * The application under test should be
+ * built with debugMode flag enabled in order to get access to its container
+ * on the internal file system.
  *
- * @param remotePath Path to file to write data to on remote device
+ * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
+ *
+ * @param remotePath Path to file to write data to on remote device.
+ * If the path starts with <em>@applicationId/</em> prefix, then the file
+ * will be pushed to the root of the corresponding application container.
  * @param file is a file to write to remote device
  * @throws IOException when there are problems with a file or current file system
  */

src/main/java/io/appium/java_client/ios/PushesFiles.java

@@ -31,14 +31,21 @@ public interface PushesFiles extends ExecutesMethod {
 
  /**
  * Saves base64 encoded data as a media file on the remote mobile device.
- * This method is only supported on Simulator running Xcode SDK 8.1+.
+ * The server should have ifuse
+ * libraries installed and configured properly for this feature to work
+ * on real devices.
+ *
+ * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page</a>
+ * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
  *
  * @param remotePath Path to file to write data to on remote device
- * Only the filename part matters there, so the remote end
+ * Only the filename part matters there on Simulator, so the remote end
  * can figure out which type of media data it is and save
  * it into a proper folder on the target device. Check
  * 'xcrun simctl addmedia' output to get more details on
- * supported media types
+ * supported media types.
+ * If the path starts with <em>@applicationId/</em> prefix, then the file
+ * will be pushed to the root of the corresponding application container.
  * @param base64Data Base64 encoded byte array of media file data to write to remote device
  */
  default void pushFile(String remotePath, byte[] base64Data) {
@@ -47,7 +54,12 @@ default void pushFile(String remotePath, byte[] base64Data) {
 
  /**
  * Saves base64 encoded data as a media file on the remote mobile device.
- * This method is only supported on Simulator running Xcode SDK 8.1+.
+ * The server should have ifuse
+ * libraries installed and configured properly for this feature to work
+ * on real devices.
+ *
+ * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page</a>
+ * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
  *
  * @param remotePath See the documentation on {@link #pushFile(String, byte[])}
  * @param file Is an existing local file to be written to the remote device