chore: Documentation changes for the next release (#1073)

box · Aug 10, 2022 · fa664f4 · fa664f4
1 parent e943d36
commit fa664f4
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 32 deletions.
diff --git a/doc/folders.md b/doc/folders.md
@@ -121,26 +121,25 @@ long offset = 0;
 long limit = 100;
 PagingParameters paging = PagingParameters.offset(offset, limit)
 Iterable<BoxItem.Info> itemIterator = childFolder.getChildren(sorting, paging);
-while (itemIterator.hasNext()){
+while (itemIterator.hasNext()) {
     BoxItem.Info itemInfo=itemIterator.next();
     // Do something
 }
 ```
 
 With offset pagination you cannot set offset larger than 300000.
-
-By default, SDK is using marker based pagination to get items. 
 With marker based pagination you can iterate over folders containing more than 300000 elements.
-If you want to use PagingParameters to start marker based pagination: 
+With marker based pagination you cannot use sorting. Use `SortParameters.none()` to turn off sort.
+If you want to use PagingParameters to start marker based pagination do: 
 ```java
 BoxFolder folder = new BoxFolder(this.api, "12345");
-// setup descending sorting by name
-SortParameters sorting = SortParameters.descending("name");
+// disable sorting
+SortParameters sorting = SortParameters.none();
 // setup paging with makred based pagination and limit 100
 long limit = 100;
 PagingParameters paging = PagingParameters.marker(limit)
 Iterable<BoxItem.Info> itemIterator = childFolder.getChildren(sorting, paging);
-while (itemIterator.hasNext()){
+while (itemIterator.hasNext()) {
     BoxItem.Info itemInfo=itemIterator.next();
     // Do something
 }

diff --git a/doc/logging.md b/doc/logging.md
@@ -15,15 +15,14 @@ By default, the `Java Util Logging` prints to console output only messages that
 can limit what is being logged by setting desired level on `com.box.sdk` logger like this:
 
 ```java
-import java.util.logging.Logger;
-import java.util.logging.Level;
+import com.box.sdk.BoxLogger;
 
-Logger.getLogger("com.box.sdk").setLevel(Level.SEVERE)
+BoxLogger.defaultLogger().setLevelToError();
 ```
 
 Example above will limit printed logs to `SEVERE` level only.
 
-### Getting FINE logs printed
+### Getting FINE (ALL) logs printed
 
 By default `FINE` level logs are not printed to the console. There are several ways to do that.   
 One way is to define custom handler:
@@ -34,19 +33,24 @@ import java.util.logging.Handler;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
-Logger sdkLogger=Logger.getLogger("com.box.sdk");
-Handler systemOut=new ConsoleHandler();
+Logger sdkLogger = BoxLogger.defaultLogger();
+Handler systemOut = new ConsoleHandler();
 // this handler will print any message to System.out
 systemOut.setLevel(Level.ALL);
 sdkLogger.addHandler(systemOut);
 // allow sdk logger to print FINE logs
-sdkLogger.setLevel(Level.FINE);
+sdkLogger.setLevelToAll();
 // prevent logs from being processed by default Console handler
 sdkLogger.setUseParentHandlers(false);
 ```
 
 you can do this in your aplication initialization.
 
+### Turn logging off
+
+To disable logging use `BoxLogger.defaultLogger().turnLoggingOff()`.
+
+
 ## Putting SDK logs into application logs
 
 If you are using different logging solution like Log4J2 or Logstash you can use SLF4J and proper bridgge to get your
@@ -81,10 +85,13 @@ this configuration to your logback.xml file:
 
 Below is a list of log levels used by SDK and coresponding Logback levels:
 
-|          SDK          | Logback |
-:-------------------:   | :-------:
-|         FINE          | DEBUG | 
-|        WARNING        | WARN  | 
-|        SEVERE         | ERROR |
+|  SDK   | Logback |
+:------:|:-------:
+|  ALL   |   ALL   | 
+|  OFF   |   OFF   | 
+|  FINE  |  DEBUG  | 
+|  INFO  |  INFO   | 
+|  WARN  |  WARN   | 
+| SEVERE |  ERROR  |
 
 You can read more on java Util Logging to SLF4J bridge [here](http://www.slf4j.org/legacy.html#jul-to-slf4j).
diff --git a/doc/trash.md b/doc/trash.md
@@ -25,15 +25,43 @@ Get Trashed Items
 The [`BoxTrash`][trash-object] implements `Iterable<BoxItem.Info>`, so to get
 the collection of items currently in the trash, simply iterate over it.
 
-<!-- sample get_trash -->
+<!-- sample get_folders_trash_items -->
 ```java
 BoxTrash trash = new BoxTrash(api);
 for (BoxItem.Info itemInfo : trash) {
-    // Process the item
+  // Process the item
 }
 ```
 
-[trash-object]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html
+Alternatively you can specify sort order, limit, use marker based pagination or specify which fields you want to extract with
+[`BoxTrash#items`][trash-items].
+
+To use sorting you have to use offset based pagination:
+```java
+BoxTrash trash = new BoxTrash(api);
+Iterable<BoxItem.Info> trashEntries = trash.items(
+  SortParameters.ascending("name"),
+  PagingParameters.offset(0, 500)
+);
+for (BoxItem.Info trashEntry : trashEntries) {
+  // Process the item
+}
+```
+If you have a lot of items in trash and offset value is in tens of thousands it is better to use marker based pagination.
+However, marker based pagination cannot be used with sorting. To disable sorting use `SortParameters.none()`:
+```java
+BoxTrash trash = new BoxTrash(api);
+Iterable<BoxItem.Info> trashEntries = trash.items(
+  SortParameters.none(),
+  PagingParameters.marker(500)
+);
+for (BoxItem.Info trashEntry : trashEntries) {
+  // Process the item
+}
+```
+
+[trash-object]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html
+[trash-items]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#items-com.box.sdk.SortParameters-com.box.sdk.PagingParameters-java.lang.String...-
 
 Get Trashed File Information
 ----------------------------
@@ -52,8 +80,8 @@ BoxTrash trash = new BoxTrash(api);
 BoxFile.Info fileInfo = trash.getFileInfo(fileID);
 ```
 
-[get-trashed-file]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFileInfo-java.lang.String-
-[get-trashed-file-fields]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFileInfo-java.lang.String-java.lang.String...-
+[get-trashed-file]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFileInfo-java.lang.String-
+[get-trashed-file-fields]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFileInfo-java.lang.String-java.lang.String...-
 
 Get Trashed Folder Information
 ------------------------------
@@ -72,8 +100,8 @@ BoxTrash trash = new BoxTrash(api);
 BoxFolder.Info folderInfo = trash.getFolderInfo(folderInfo);
 ```
 
-[get-trashed-folder]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFolderInfo-java.lang.String-
-[get-trashed-folder-fields]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFolderInfo-java.lang.String-java.lang.String...-
+[get-trashed-folder]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFolderInfo-java.lang.String-
+[get-trashed-folder-fields]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFolderInfo-java.lang.String-java.lang.String...-
 
 
 Permanently Delete File From Trash
@@ -91,7 +119,7 @@ BoxTrash trash = new BoxTrash(api);
 trash.deleteFile(fileID);
 ```
 
-[delete-file]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#deleteFile-java.lang.String-
+[delete-file]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#deleteFile-java.lang.String-
 
 
 Permanently Delete Folder From Trash
@@ -109,7 +137,7 @@ BoxTrash trash = new BoxTrash(api);
 trash.deleteFolder(folderID);
 ```
 
-[delete-folder]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#deleteFolder-java.lang.String-
+[delete-folder]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#deleteFolder-java.lang.String-
 
 Restore a File from the Trash
 -----------------------------
@@ -132,8 +160,8 @@ BoxTrash trash = new BoxTrash(api);
 trash.restoreFile(fileID, newName, newParentID);
 ```
 
-[restore-file]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFile-java.lang.String-
-[restore-file-safe]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFile-java.lang.String-java.lang.String-java.lang.String-
+[restore-file]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFile-java.lang.String-
+[restore-file-safe]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFile-java.lang.String-java.lang.String-java.lang.String-
 
 Restore a Folder from the Trash
 -------------------------------
@@ -157,5 +185,5 @@ BoxTrash trash = new BoxTrash(api);
 trash.restoreFolder(folderID, newName, newParentID);
 ```
 
-[restore-folder]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFolder-java.lang.String-
-[restore-folder-safe]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFolder-java.lang.String-java.lang.String-java.lang.String-
+[restore-folder]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFolder-java.lang.String-
+[restore-folder-safe]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFolder-java.lang.String-java.lang.String-java.lang.String-