Merge pull request #36 from microsoftgraph/iambmelt/work

Release 1.2.0

Author: iambmelt

README.md

@@ -15,7 +15,7 @@ repository {
 
 dependency {
     // Include the sdk as a dependency
-    compile('com.microsoft.graph:msgraph-sdk-android:1.1.+')
+    compile('com.microsoft.graph:msgraph-sdk-android:1.2.+')
 
     // Include the gson dependency
     compile('com.google.code.gson:gson:2.3.1')
@@ -84,6 +84,7 @@ For a more detailed documentation see:
 
 * [Overview](docs/overview.md)
 * [Extensibility](docs/extensibility.md)
+* [Handling Open Types, PATCH support with `null` values](docs/additional_data.md)
 * [Collections](docs/collections.md)
 * [Errors](docs/errors.md)
 * [Contributions](docs/contributions.md)

docs/opentypes.md

@@ -0,0 +1,72 @@
+# Working with Open Types
+The Microsoft Graph SDK for Android allows you to capture, inspect, modify, and export properties not captured by the SDK's built-in native entity definitions.
+
+Suppose you have an `EntityType` describing a Vehicle:
+```xml
+<EntityType Name="vehicle" BaseType="your.namespace.entity" OpenType="true">
+   <Property Name="make" Type="Edm.String" Unicode="false" />
+   <Property Name="model" Type="Edm.String" Unicode="false" />
+   <Property Name="modelYear" Type="Edm.Int32" />
+</EntityType>
+```
+
+Represented as JSON, this object might take the following form:
+```json
+{
+    "id": "9043ff12-6046-495f-8a0f-4a0f65a3f288",
+    "make": "Chase Motor Truck Company",
+    "model": "Model M",
+    "modelYear": "1912"
+}
+```
+
+As a native Java object, you might choose to implement this entity thusly:
+```java
+class Vehicle extends BaseEntity {
+    String make;
+    String model;
+    Year modelYear;
+}
+```
+
+Because `vehicle` is defined as an `OpenType`, additional undeclared properties may be sent by the web service: in this case, a license plate number.
+
+```json
+{
+    "id": "9043ff12-6046-495f-8a0f-4a0f65a3f288",
+    "make": "Chase Motor Truck Company",
+    "model": "Model M",
+    "modelYear": "1912",
+    "licensePlate": "MSGRAPH4U"
+}
+```
+
+With the addition of the `AdditionalDataManager` (as of `v1.1.1`), capture and transmission of such properties is supported through a transient native property.
+
+## Examples
+
+### Querying undeclared properties
+Using the above example, we'll query our vehicle entity for the undeclared `licensePlate` property:
+
+```java
+// Load a Vehicle
+Vehicle vehicle = getVehicleById("<some id>");
+
+// Access the licensePlate property
+String licensePlate = 
+    vehicle
+        .getAdditionalDataManager()
+        .get("licensePlate")
+        .getAsString();
+```
+
+### Initialize undeclared properties
+To specify an undeclared property, the following syntax may be used:
+
+```java
+vehicle
+    .getAdditionalDataManager()
+    .put("numberOfDoors", new JsonPrimitive(0));
+```
+
+This syntax supports all null, object, array, and primitive JSON structures.

docs/overview.md

@@ -168,3 +168,12 @@ graphServiceClient()
         }
     });
  ```
+
+## Setting properties to `null`
+To support PATCH operations involving `null` values, specify the property name you wish to nullify:
+
+```java
+user
+    .getAdditionalDataManager()
+    .put("officeLocation", JsonNull.INSTANCE);
+```

gradle.properties

@@ -22,6 +22,6 @@ mavenRepoUrl         = https://api.bintray.com/maven/microsoftgraph/Maven/msgrap
 mavenGroupId         = com.microsoft.graph
 mavenArtifactId      = msgraph-sdk-android
 mavenMajorVersion    = 1
-mavenMinorVersion    = 1
+mavenMinorVersion    = 2
 mavenPatchVersion    = 0
 nightliesUrl         = http://dl.bintray.com/MicrosoftGraph/Maven

graphsdk/src/androidTest/java/com/microsoft/graph/extensions/ManualExtensionsTests.java

@@ -0,0 +1,31 @@
+package com.microsoft.graph.extensions;
+
+import android.test.AndroidTestCase;
+
+import junit.framework.Assert;
+
+/**
+ * These tests verify that manually-written classes are preserved from version-to-version.
+ *
+ * @author brianmel
+ */
+public class ManualExtensionsTests extends AndroidTestCase {
+
+    public void testChunkedUploadRequestPreserved() {
+        final String className = "com.microsoft.graph.extensions.ChunkedUploadRequest";
+        try {
+            Class.forName(className);
+        } catch (ClassNotFoundException e) {
+            Assert.fail("Extension [" + className + "] not found.");
+        }
+    }
+
+    public void testChunkedUploadResultPreserved() {
+        final String className = "com.microsoft.graph.extensions.ChunkedUploadResult";
+        try {
+            Class.forName(className);
+        } catch (ClassNotFoundException e) {
+            Assert.fail("Extension [" + className + "] not found.");
+        }
+    }
+}

graphsdk/src/androidTest/java/com/microsoft/graph/http/MockConnection.java

@@ -14,7 +14,7 @@
 public class MockConnection implements IConnection {
 
     private final ITestConnectionData mData;
-    private HashMap<String, String> mHeaders = new HashMap<String, String>();
+    private HashMap<String, String> mHeaders = new HashMap<>();
     private Boolean mFollowRedirects;
 
     public MockConnection(ITestConnectionData data) {
@@ -28,7 +28,7 @@ public void setFollowRedirects(boolean followRedirects) {
 
     @Override
     public void addRequestHeader(String headerName, String headerValue) {
-        mHeaders.put(headerName,headerValue);
+        mHeaders.put(headerName, headerValue);
     }
 
     @Override
@@ -70,4 +70,10 @@ public String getRequestMethod() {
     public int getContentLength() {
         return mData.getJsonResponse().length();
     }
+
+    @Override
+    public void setContentLength(int length) {
+        // noop
+    }
+
 }

graphsdk/src/androidTest/java/com/microsoft/graph/http/MockHttpProvider.java

@@ -102,6 +102,11 @@ public <Result, BodyType> Result send(IHttpRequest request,
         return null;
     }
 
+    @Override
+    public <Result, BodyType, DeserializeType> Result send(IHttpRequest request, Class<Result> resultClass, BodyType serializable, IStatefulResponseHandler<Result, DeserializeType> handler) throws ClientException {
+        return null;
+    }
+
     void setConnectionFactory(final IConnectionFactory factory) {
         mConnectionFactory = factory;
     }

graphsdk/src/main/java/com/microsoft/graph/concurrency/ChunkedUploadProvider.java

@@ -0,0 +1,196 @@
+// ------------------------------------------------------------------------------
+// Copyright (c) 2015 Microsoft Corporation
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+// ------------------------------------------------------------------------------
+
+package com.microsoft.graph.concurrency;
+
+
+import com.microsoft.graph.concurrency.ChunkedUploadResponseHandler;
+import com.microsoft.graph.concurrency.IProgressCallback;
+import com.microsoft.graph.extensions.ChunkedUploadRequest;
+import com.microsoft.graph.extensions.ChunkedUploadResult;
+import com.microsoft.graph.extensions.IGraphServiceClient;
+import com.microsoft.graph.extensions.UploadSession;
+import com.microsoft.graph.options.Option;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.security.InvalidParameterException;
+import java.util.List;
+
+/**
+ * ChunkedUpload service provider.
+ *
+ * @param <UploadType> The upload item type.
+ */
+public class ChunkedUploadProvider<UploadType> {
+
+    /**
+     * The default chunk size for upload. Currently set to 5 MiB.
+     */
+    private static final int DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
+
+    /**
+     * The required chunk size increment by OneDrive Service, which is 320 KiB.
+     */
+    private static final int REQUIRED_CHUNK_SIZE_INCREMENT = 320 * 1024;
+
+    /**
+     * The maximum chunk size for a single upload allowed by OneDrive service.
+     * Currently the value is 60 MiB.
+     */
+    private static final int MAXIMUM_CHUNK_SIZE = 60 * 1024 * 1024;
+
+    /**
+     * The default retry times for a simple chunk upload if failure happened.
+     */
+    private static final int MAXIMUM_RETRY_TIMES = 3;
+
+    /**
+     * The client.
+     */
+    private final IGraphServiceClient mClient;
+
+    /**
+     * The input stream.
+     */
+    private final InputStream mInputStream;
+
+    /**
+     * The upload session url.
+     */
+    private final String mUploadUrl;
+
+    /**
+     * The stream size.
+     */
+    private final int mStreamSize;
+
+    /**
+     * The upload response handler.
+     */
+    private final ChunkedUploadResponseHandler<UploadType> mResponseHandler;
+
+    /**
+     * The counter for how many bytes read from input stream.
+     */
+    private int mReadSoFar;
+
+    /**
+     * Create the ChunkedUploadProvider
+     *
+     * @param uploadSession   The initial upload session.
+     * @param client          The onedrive client.
+     * @param inputStream     The input stream.
+     * @param streamSize      The stream size.
+     * @param uploadTypeClass The upload type class.
+     */
+    public ChunkedUploadProvider(final UploadSession uploadSession,
+                                 final IGraphServiceClient client,
+                                 final InputStream inputStream,
+                                 final int streamSize,
+                                 final Class<UploadType> uploadTypeClass) {
+        if (uploadSession == null) {
+            throw new InvalidParameterException("Upload session is null.");
+        }
+
+        if (client == null) {
+            throw new InvalidParameterException("OneDrive client is null.");
+        }
+
+        if (inputStream == null) {
+            throw new InvalidParameterException("Input stream is null.");
+        }
+
+        if (streamSize <= 0) {
+            throw new InvalidParameterException("Stream size should larger than 0.");
+        }
+
+        this.mClient = client;
+        this.mReadSoFar = 0;
+        this.mInputStream = inputStream;
+        this.mStreamSize = streamSize;
+        this.mUploadUrl = uploadSession.uploadUrl;
+        this.mResponseHandler = new ChunkedUploadResponseHandler(uploadTypeClass);
+    }
+
+    /**
+     * Upload content to remote upload session based on the input stream.
+     *
+     * @param options  The upload options.
+     * @param callback The progress callback invoked during uploading.
+     * @param configs  The optional ocnfigs for the upload options, [0] should be the customized chunk
+     *                 size and the [1] should be the maxRetry for upload retry.
+     * @throws IOException The io exception happend during upload.
+     */
+    public void upload(final List<Option> options,
+                       final IProgressCallback<UploadType> callback,
+                       final int... configs)
+            throws IOException {
+        int chunkSize = DEFAULT_CHUNK_SIZE;
+
+        if (configs.length > 0) {
+            chunkSize = configs[0];
+        }
+
+        int maxRetry = MAXIMUM_RETRY_TIMES;
+
+        if (configs.length > 1) {
+            maxRetry = configs[1];
+        }
+
+        if (chunkSize % REQUIRED_CHUNK_SIZE_INCREMENT != 0) {
+            throw new IllegalArgumentException("Chunk size must be a multiple of 320 KiB");
+        }
+
+        if (chunkSize > MAXIMUM_CHUNK_SIZE) {
+            throw new IllegalArgumentException("Please set chunk size smaller than 60 MiB");
+        }
+
+        byte[] buffer = new byte[chunkSize];
+
+        while (this.mReadSoFar < this.mStreamSize) {
+            int read = this.mInputStream.read(buffer);
+
+            if (read == -1) {
+                break;
+            }
+
+            ChunkedUploadRequest request =
+                    new ChunkedUploadRequest(this.mUploadUrl, this.mClient, options, buffer, read,
+                            maxRetry, this.mReadSoFar, this.mStreamSize);
+            ChunkedUploadResult result = request.upload(this.mResponseHandler);
+
+            if (result.uploadCompleted()) {
+                callback.progress(this.mStreamSize, this.mStreamSize);
+                callback.success((UploadType) result.getItem());
+                break;
+            } else if (result.chunkCompleted()) {
+                callback.progress(this.mReadSoFar, this.mStreamSize);
+            } else if (result.hasError()) {
+                callback.failure(result.getError());
+                break;
+            }
+
+            this.mReadSoFar += read;
+        }
+    }
+}