chore: documentation update

doc/events.md

@@ -11,7 +11,7 @@ handles long-polling and deduplicating events.
 - [User Events](#user-events)
   - [Deduplicating Events](#deduplicating-events)
 - [Enterprise (Admin) Events](#enterprise-admin-events)
-  - [Historical Querying](#historical-querying) 
+  - [Historical Querying](#historical-querying)
   - [Live Monitoring](#live-monitoring)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -62,11 +62,11 @@ ignore them.
 
 ### Historical Querying
 
-The Box API provides an `EventLog` class and a 
+The Box API provides an `EventLog` class and a
 `getEnterpriseEvents(BoxAPIConnection api, EnterpriseEventsRequest enterpriseEventsRequest)` method
 that reads from the `admin-logs` stream and returns an `Iterable<BoxEvent>` over
 Enterprise [`BoxEvent`][box-event] records. The emphasis for this stream is on completeness over latency,
-which means that Box will deliver admin events in chronological order and without duplicates, 
+which means that Box will deliver admin events in chronological order and without duplicates,
 but with higher latency. You can specify start and end time/dates. This method
 will only work with an API connection for an enterprise admin account or service account with a manage enterprise properties.
 
@@ -124,6 +124,26 @@ for (BoxEvent event : eventLog){
 };
 ```
 
+You can also filter events by type name. This is usefull if a new event type is introduced and is not mapped to
+`BoxEvent.EventType`.
+```java
+// filter events by type name
+EnterpriseEventsRequest request = new EnterpriseEventsRequest()
+  .typeNames("ITEM_CREATE", "ITEM_OPEN");
+EventLog eventLog = EventLog.getEnterpriseEvents(api, request);
+for (BoxEvent event : eventLog){
+  System.out.println("Enterprise Event Created by User: "
+    + event.getCreatedBy().getName()
+    + " Login: " + event.getCreatedBy().getLogin()
+    + " Event Type: " + event.getEventType()
+    + " Event Type Name: " + event.getTypeName()
+    + " Created at: " + event.getCreatedAt().toString()
+  );
+};
+```
+Bear in mind that if an event type is not mapped to `BoxEvent.EventType` the value of `BoxEvent#getEventType()` will
+be `BoxEvent.EventType.UNKNOWN` but `BoxEvent#getTypeName()` will return its name.
+
 If you want to progress within a stream you can use position parameter:
 ```java
 EnterpriseEventsRequest request1 = new EnterpriseEventsRequest().limit(20);
@@ -137,8 +157,8 @@ EventLog eventLog2 = EventLog.getEnterpriseEvents(api, request2);
 
 ### Live Monitoring
 To monitor recent events that have been generated within Box across the enterprise use
-`EventLog#getEnterpriseEventsStream(BoxAPIConnection api, EnterpriseEventsStreamRequest enterpriseEventsStreamRequest)`, 
-method that reads from the `admin-logs-streaming` stream and returns an `Iterable<BoxEvent>` over 
+`EventLog#getEnterpriseEventsStream(BoxAPIConnection api, EnterpriseEventsStreamRequest enterpriseEventsStreamRequest)`,
+method that reads from the `admin-logs-streaming` stream and returns an `Iterable<BoxEvent>` over
 Enterprise [`BoxEvent`][box-event] records.
 The emphasis for this feed is on low latency rather than chronological accuracy, which means that Box may return
 events more than once and out of chronological order. Events are returned via the API around 12 seconds after they
@@ -185,6 +205,26 @@ for (BoxEvent event : eventLog){
 };
 ```
 
+You can also filter events by type name. This is usefull if a new event type is introduced and is not mapped to
+`BoxEvent.EventType`.
+```java
+// filter events by type name
+EnterpriseEventsRequest request = new EnterpriseEventsStreamRequest()
+  .typeNames("ITEM_CREATE", "ITEM_OPEN");
+EventLog eventLog = EventLog.getEnterpriseEventsStream(api, request);
+for (BoxEvent event : eventLog){
+  System.out.println("Enterprise Event Created by User: "
+    + event.getCreatedBy().getName()
+    + " Login: " + event.getCreatedBy().getLogin()
+    + " Event Type: " + event.getEventType()
+    + " Event Type Name: " + event.getTypeName()
+    + " Created at: " + event.getCreatedAt().toString()
+  );
+};
+```
+Bear in mind that if an event type is not mapped to `BoxEvent.EventType` the value of `BoxEvent#getEventType()` will
+be `BoxEvent.EventType.UNKNOWN` but `BoxEvent#getTypeName()` will return its name.
+
 If you want to progress within a stream you can use position parameter:
 ```java
 EnterpriseEventsStreamRequest request1 = new EnterpriseEventsStreamRequest().limit(20);
@@ -195,7 +235,7 @@ EnterpriseEventsStreamRequest request2 = new EnterpriseEventsStreamRequest().lim
 EventLog eventLog2 = EventLog.getEnterpriseEventsStream(api, request2);
 // process revieved events
 ```
-If you have the next stream position, and make a subsequent call, the API will return immediately 
+If you have the next stream position, and make a subsequent call, the API will return immediately
 even when there are no events, the next stream position will be returned.
-If you have a stream position that is older than two weeks than API will return no events and next 
-stream position.
+If you have a stream position that is older than two weeks than API will return no events and next
+stream position.

doc/files.md

@@ -479,18 +479,30 @@ Get Previous Versions of a File
 -------------------------------
 
 For users with premium accounts, versions of a file can be retrieved with the
-[`getVersions()`][get-versions] method.
+[`getVersions()`][get-versions] method. It will return versions with all default fields set.
 
 <!-- sample get_files_id_versions -->
 ```java
 BoxFile file = new BoxFile(api, "id");
 Collection<BoxFileVersion> versions = file.getVersions();
 for (BoxFileVersion version : versions) {
-    System.out.format("SHA1 of \"%s\": %s\n", item.getName(), version.getSha1());
+    System.out.format("SHA1 of \"%s\": %s\n", file.getInfo().getName(), version.getSha1());
 }
 ```
 
+You can specify selected fields to be returned while getting versions information. 
+Assume we want to get version SHA1 and version number:
+```java
+BoxFile file = new BoxFile(api, "id");
+Collection<BoxFileVersion> versions = file.getVersions("sha1", "version_number");
+for (BoxFileVersion version : versions) {
+    System.out.format("SHA1 of \"%d\": %s\n", version.getVersionNumber(), version.getSha1());
+}
+```
+You can find a list of available fields at [`BoxFile.ALL_VERSION_FIELDS`][versions-fields].
+
 [get-versions]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getVersions--
+[versions-fields]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#ALL_VERSION_FIELDS--
 
 Upload a New Version of a File
 ------------------------------
@@ -648,7 +660,7 @@ Create a Shared Link
 A shared link for a file can be generated by calling
 [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`][create-shared-link].
 
-<!-- sample put_files_id add_shared_link -->
+<!-- sample put_files_id_shared_link_create -->
 ```java
 // Optionally we can calculate and set the date when shared link will automatically be disabled
 final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7;
@@ -693,7 +705,6 @@ Update a Shared Link
 A shared link for a file can be updated by calling the same method as used when creating a shared link,
 [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`][create-shared-link].
 
-<!-- sample put_files_id update_shared_link -->
 ```java
 BoxFile file = new BoxFile(api, "id");
 BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest()

doc/folders.md

@@ -315,7 +315,7 @@ Create a Shared Link
 A shared link for a folder can be generated by calling
 [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`][create-shared-link].
 
-<!-- sample put_folders_id add_shared_link -->
+<!-- sample put_folders_id_shared_link_create -->
 ```java
 // Optionally we can calculate and set the date when shared link will automatically be disabled
 final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7;
@@ -360,7 +360,6 @@ Update a Shared Link
 A shared link for a folder can be updated by calling the same method as used when creating a shared link,
 [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`][create-shared-link].
 
-<!-- sample put_folders_id update_shared_link -->
 ```java
 BoxFolder folder = new BoxFolder(api, "id");
 BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest()

doc/retention_policies.md

@@ -47,9 +47,11 @@ object.
 
 ```java
 String notifiedUserID = "12345";
+String description = "Policy to retain all reports";
 RetentionPolicyParams optionalParams = new RetentionPolicyParams();
 optionalParams.setCanOwnerExtendRetention(true);
 optionalParams.setAreOwnersNotified(true);
+optionalParams.setDescription(description);
 optionalParams.addCustomNotificationRecipient(notifiedUserID);
 
 // Create indefinite policy with optional parameters
@@ -157,21 +159,25 @@ Create Retention Policy Assignment
 ----------------------------------
 To create new retention policy assignment call [`assignTo(BoxFolder target)`][create-assignment] method to assign the policy
 to a specific folder, [`assignToEnterprise()`][create-assignment-to-enterprise] to assign the retention policy to the
-entire enterprise, or [`assignToMetadataTemplate(String templateID, MetadataFieldFilter... filterFields)`][assign-to-metadata]
+entire enterprise, or [`assignToMetadataTemplate(String templateID, String startDateField, MetadataFieldFilter... filterFields)`][assign-to-metadata]
 to assign the policy to items with a specific metadata template.
 
 <!-- sample post_retention_policy_assignments -->
 ```java
 // Assign the policy to the entire enterprise
 BoxRetentionPolicy policy = new BoxRetentionPolicy(api, policyID);
-BoxRetentionPolicyAssignment.Info enterpriseAssignmentInfo = policy.assignToEnterprise();
+policy.assignToEnterprise();
 
 // Assign the policy to a single folder
 BoxFolder folder = new BoxFolder(api, folderID);
-BoxRetentionPolicyAssignment.Info folderAssignmentInfo = policy.assignTo(folder);
-
-// Assign the policy to all items with metadata template "f0dce190-8106-43ca-9d67-7dce9b10a55e"
-BoxRetentionPolicyAssignment.Info metadataAssignmentInfo = policy.assignToMetadataTemplate("f0dce190-8106-43ca-9d67-7dce9b10a55e");
+policy.assignTo(folderID);
+
+// Assign the policy to all items with metadata template
+String metadataTemplateID = "f0dce190-8106-43ca-9d67-7dce9b10a55e";
+policy.assignToMetadataTemplate(metadataTemplateID);
+// You can also pass an optional `startDateField` parameter containing the ID of the metadata template's `date` field
+String dateFieldID = "fb523725-04b1-4502-b871-eac305274533";
+policy.assignToMetadataTemplate(metadataTemplateID, dateFieldID);
 ```
 
 [create-assignment]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#assignTo-com.box.sdk.BoxFolder-
@@ -263,14 +269,16 @@ Get File Versions Under Retention For Assignment
 
 To get an iterable with all file versions under retention for assignment
 policy, call the [`getFileVersionsUnderRetention(BoxAPIConnection api, int limit, String... fields)`][get-file-versions-under-retention-for-assignment]
-method. This will return an interable with [`BoxFileVersion`][file-version] objects containing information about the file versions.
+method. This will return an interable with [`BoxFile.Info`][file] objects containing information about the file.
+You can get version by calling [`BoxFile.Info#getVersion()`][file-version].
 
 <!-- sample get_file_versions_under_retention_for_assignment -->
 ```java
 BoxRetentionPolicyAssignment policyAssignment = new BoxRetentionPolicyAssignment(api, id);
-Iterable<BoxFileVersion> fileVersionsUnderRetention = policyAssignment.getFileVersionsUnderRetention();
-for (BoxFileVersion fileVersion : fileVersionsUnderRetention){
-	// Do something with the file versions under retention.
+Iterable<BoxFile.Info> fileVersionsUnderRetention = policyAssignment.getFileVersionsUnderRetention();
+for (BoxFile.Info file : fileVersionsUnderRetention){
+    BoxFileVersion version = file.getVersion();
+    // Do something with the file version under retention.
 }
 ```
 

doc/weblinks.md

@@ -13,6 +13,8 @@ similarly to file objects.
 - [Get Web Link](#get-web-link)
 - [Update Web Link](#update-web-link)
 - [Delete Web Link](#delete-web-link)
+- [Create Shared Link](#create-shared-link)
+- [Remove Shared Link](#remove-shared-link)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -71,13 +73,27 @@ webLink.updateInfo(webLinkInfo);
 
 [update-web-link]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#updateInfo-com.box.sdk.BoxWebLink.Info-
 
-Create a Shared Link
+Delete Web Link
+---------------
+
+A web link can be deleted by calling the [`delete()`][delete] method.
+
+<!-- sample delete_web_links_id -->
+```java
+BoxWebLink webLink = new BoxWebLink(api, id);
+webLink.delete();
+```
+
+[delete]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#delete--
+
+Create Shared Link
 --------------------
 
 You can create a shared link for a web link by calling the
 [`createSharedLink(BoxSharedLinkWithoutPermissionsRequest sharedLinkRequest)`][create-shared-link]
 method.
 
+<!-- sample put_web_links_id_shared_link_create -->
 ```java
 // Optionally we can calculate and set the date when shared link will automatically be disabled
 final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7;
@@ -93,11 +109,12 @@ BoxSharedLink sharedLink = webLink.createSharedLink(sharedLinkRequest);
 
 [create-shared-link]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#createSharedLink-com.box.sdk.sharedlink.BoxSharedLinkWithoutPermissionsRequest-
 
-Remove a Shared Link
+Remove Shared Link
 --------------------
 
 You can remove a shared link for a web link by calling the [`removeSharedLink`](remove-shared-link) method.
 
+<!-- sample put_web_links_id_shared_link_remove -->
 ```java
 BoxWebLink webLink = new BoxWebLink(api, "12345");
 BoxWebLink.Info webLinkInfo = webLink.getInfo();
@@ -107,16 +124,3 @@ webLink.updateInfo(info)
 
 [remove-shared-link]: https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#removeSharedLink--
 
-
-Delete Web Link
----------------
-
-A web link can be deleted by calling the [`delete()`][delete] method.
-
-<!-- sample delete_web_links_id -->
-```java
-BoxWebLink webLink = new BoxWebLink(api, id);
-webLink.delete();
-```
-
-[delete]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#delete--