Merge branch 'master' into build-perf

android/modules/network/src/java/ti/modules/titanium/network/TiHTTPClient.java

@@ -189,6 +189,11 @@ private void handleResponse(HttpURLConnection connection) throws IOException
 					if (baseFile instanceof TiFile) {
 						responseFile = (TiFile) baseFile;
 					}
+				} else if (f instanceof TiFileProxy) {
+					TiBaseFile baseFile = ((TiFileProxy) f).getBaseFile();
+					if (baseFile instanceof TiFile) {
+						responseFile = (TiFile) baseFile;
+					}
 				}
 				if (responseFile == null && Log.isDebugModeEnabled()) {
 					Log.w(TAG, "Ignore the provided response file because it is not valid / writable.");

apidoc/Titanium/Network/HTTPClient.yml

@@ -100,6 +100,14 @@ description: |
 
     Starting with Release 3.6.0, you can set the TLS version for the Android and iOS platforms.
     Prior to Release 3.6.0, you can only set the TLS version for iOS.
+    
+    #### Caching Data
+
+    You can also use the HTTP client API to cache image, response data or related. A convenient
+    way to do so is by setting the <Titanium.Network.HTTPClient.file> property to a path or target
+    file, which will be populated with the response data in a successful case (e.g. in the `onload`
+    callback). For more complex use cases, make sure to check [To.ImageCache](https://github.com/Topener/To.ImageCache/)
+    which also supports expire-handling and extended cache control.
 
     #### Android Platform Implementation Notes
 
@@ -357,14 +365,11 @@ properties:
     platforms: [iphone, ipad]
 
   - name: file
-    summary: Target local file to receive data.
+    summary: Target local file or file path to receive data.
     description: |
-        On iOS, can only be set **after** calling [open](Titanium.Network.HTTPClient.open).
-
-
-        On Android, can be set anytime prior to calling [send](Titanium.Network.HTTPClient.send).
+        This property can be set anytime prior to calling [send](Titanium.Network.HTTPClient.send).
         The file must be writable such as the application data directory or temp directory.
-    type: String
+    type: [String, Titanium.Filesystem.File]
     platforms: [android, iphone, ipad]
     since: {android: 3.4.0}
 

tests/Resources/ti.network.httpclient.addontest.js

@@ -0,0 +1,44 @@
+/*
+ * Appcelerator Titanium Mobile
+ * Copyright (c) 2011-Present by Appcelerator, Inc. All Rights Reserved.
+ * Licensed under the terms of the Apache Public License
+ * Please see the LICENSE included with this distribution for details.
+ */
+/* eslint-env mocha */
+/* global Ti */
+/* eslint no-unused-expressions: "off" */
+'use strict';
+const should = require('./utilities/assertions');
+
+describe('Titanium.Network.HTTPClient', function () {
+	this.timeout(6e4);
+
+	it.windowsMissing('.file set to a Ti.Filesystem.File object', function (finish) {
+		this.timeout(6e4);
+
+		const downloadedImageFile = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, 'DownloadedImage.png');
+		if (downloadedImageFile.exists()) {
+			downloadedImageFile.deleteFile();
+		}
+
+		const xhr = Ti.Network.createHTTPClient({});
+		xhr.setTimeout(6e4);
+		xhr.onload = function (e) {
+			try {
+				// verify that the destination file now exists
+				// TODO: Verify some known contents match?
+				should(xhr.file.exists()).be.true;
+
+				finish();
+			} catch (err) {
+				finish(err);
+			}
+		};
+		xhr.onerror = e => finish(e);
+
+		xhr.open('GET', 'https://avatars1.githubusercontent.com/u/82188?s=200&v=4');
+		xhr.setRequestHeader('Accept-Encoding', 'identity');
+		xhr.file = downloadedImageFile;
+		xhr.send();
+	});
+});