Add helpers (#90)

* Add helpers * Fix whitespace
smartsheet · Jun 21, 2024 · c020eb2 · c020eb2
1 parent 0f4000f
commit c020eb2
Show file tree

Hide file tree

Showing 12 changed files with 189 additions and 25 deletions.
diff --git a/ADVANCED.md b/ADVANCED.md
@@ -341,7 +341,7 @@ public class Sample {
             Smartsheet smartsheet = SmartsheetFactory.createDefaultGovAccountClient( /* "ll352u9jujauoqz4gstvsae05" */);
 
             // List all sheets
-            PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(null, null, null );
+            PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets();
             System.out.println("\nFound " + sheets.getTotalCount() + " sheets\n");
 
             Long sheetId = sheets.getData().get(0).getId();            // Default to first sheet
@@ -350,7 +350,7 @@ public class Sample {
             // sheetId = 239236234L;
 
             // Load entire sheet
-            Sheet sheet = smartsheet.sheetResources().getSheet(sheetId, null, null, null, null, null, null, null);
+            Sheet sheet = smartsheet.sheetResources().getSheet(sheetId);
             List<Row> rows = sheet.getRows();
             System.out.println("\nLoaded sheet id " + sheetId + " with " + rows.size() + " rows, title: " + sheet.getName());
 

diff --git a/README.md b/README.md
@@ -82,11 +82,7 @@ String accessToken = "JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789";
 Smartsheet smartsheet = SmartsheetFactory.createDefaultClient(accessToken);
 
 // List all sheets
-PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(
-    null,           // EnumSet<SourceInclusion> includes
-    null,           // PaginationParameters
-    null            // Date modifiedSince
-);
+PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets();
 
 System.out.println("Found " + sheets.getTotalCount() + " sheets");
 
@@ -97,16 +93,7 @@ long sheetId = sheets.getData().get(0).getId();      // Default to first sheet
 System.out.println("Loading sheet id: " + sheetId);
 
 // Load the entire sheet
-Sheet sheet = smartsheet.sheetResources().getSheet(
-    sheetId,                // long sheetId
-    null,                   // EnumSet<SheetInclusion> includes
-    null,                   // EnumSet<ObjectExclusion> excludes
-    null,                   // Set<Long> rowIds
-    null,                   // Set<Integer> rowNumbers
-    null,                   // Set<Long> columnIds
-    null,                   // Integer pageSize
-    null                    // Integer page
-);
+Sheet sheet = smartsheet.sheetResources().getSheet(sheetId);
 System.out.println("Loaded " + sheet.getTotalRowCount() + " rows from sheet: " + sheet.getName());
 ```
 

diff --git a/src/main/java/com/smartsheet/api/SheetResources.java b/src/main/java/com/smartsheet/api/SheetResources.java
@@ -45,6 +45,20 @@
  */
 public interface SheetResources {
 
+    /**
+     * List all sheets.
+     * <p>
+     * It mirrors to the following Smartsheet REST API method: GET /sheets
+     * @return A list of all sheets (note that an empty list will be returned if there are none).
+     * @throws IllegalArgumentException if any argument is null or empty string
+     * @throws InvalidRequestException if there is any problem with the REST API request
+     * @throws AuthorizationException if there is any problem with  the REST API authorization (access token)
+     * @throws ResourceNotFoundException if the resource cannot be found
+     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
+     * @throws SmartsheetException if there is any other error during the operation
+     */
+    PagedResult<Sheet> listSheets() throws SmartsheetException;
+
     /**
      * <p>List all sheets.</p>
      *
@@ -201,6 +215,21 @@ Sheet getSheet(long id,
                           Integer ifVersionAfter,
                           Integer level) throws SmartsheetException;
 
+    /**
+     * <p>Get sheet by ID. Load all row and column data</p>
+     *
+     * @param sheetId id of the sheet to fetch
+     * @return the sheet resource (note that if there is no such resource, this method will throw
+     *     ResourceNotFoundException rather than returning null).
+     * @throws IllegalArgumentException if any argument is null or empty string
+     * @throws InvalidRequestException if there is any problem with the REST API request
+     * @throws AuthorizationException if there is any problem with  the REST API authorization (access token)
+     * @throws ResourceNotFoundException if the resource cannot be found
+     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
+     * @throws SmartsheetException if there is any other error during the operation
+     */
+    Sheet getSheet(long sheetId) throws SmartsheetException;
+
     /**
      * <p>Get a sheet as an Excel file.</p>
      *

diff --git a/src/main/java/com/smartsheet/api/SheetRowResources.java b/src/main/java/com/smartsheet/api/SheetRowResources.java
@@ -16,12 +16,14 @@
 
 package com.smartsheet.api;
 
+import com.smartsheet.api.models.Cell;
 import com.smartsheet.api.models.CopyOrMoveRowDirective;
 import com.smartsheet.api.models.CopyOrMoveRowResult;
 import com.smartsheet.api.models.MultiRowEmail;
 import com.smartsheet.api.models.PartialRowUpdateResult;
 import com.smartsheet.api.models.Row;
 import com.smartsheet.api.models.RowEmail;
+import com.smartsheet.api.models.Sheet;
 import com.smartsheet.api.models.enums.ObjectExclusion;
 import com.smartsheet.api.models.enums.RowCopyInclusion;
 import com.smartsheet.api.models.enums.RowInclusion;
@@ -270,6 +272,42 @@ List<Row> updateRows(
             EnumSet<ObjectExclusion> excludes
     ) throws SmartsheetException;
 
+    /**
+     * <p>Helper method: Update a single cell</p>
+     *
+     * @param sheetId the sheet ID the cell should be written to
+     * @param cell the cell object to be written. Must include a rowId and columnId
+     * @return The returned Row object from the api
+     * @throws SmartsheetException the smartsheet exception
+     */
+    Row updateCell(long sheetId, Cell cell) throws SmartsheetException;
+
+    /**
+     * <p>Helper method: Update a single with a string value</p>
+     * <p>NOTE: This method internally fetches the sheet. To avoid this step, fetch the sheet in
+     * advance and use the method by the same name</p>
+     *
+     * @param sheetId the sheet ID the cell should be written to
+     * @param rowIdx the row index of the cell (base 1 indexed)
+     * @param colIdx the column index of the cell (base 1 indexed)
+     * @param newValue the new value of the cell
+     * @return The returned Row object from the api
+     * @throws SmartsheetException the smartsheet exception
+     */
+    Row updateCell(long sheetId, int rowIdx, int colIdx, String newValue) throws SmartsheetException;
+
+    /**
+     * <p>Helper method: Update a single with a string value</p>
+     *
+     * @param sheet The sheet to update the cell in. Must include rowId and cell information
+     * @param rowIdx The row index of the cell (base 1 indexed)
+     * @param colIdx The column index of the cell (base 1 indexed)
+     * @param newValue The new value of the cell
+     * @return The returned Row object from the api
+     * @throws SmartsheetException the smartsheet exception
+     */
+    Row updateCell(Sheet sheet, int rowIdx, int colIdx, String newValue) throws SmartsheetException;
+
     /**
      * <p>Update rows, but allow partial success. The PartialRowUpdateResult will contain the successful
      * rows and those that failed, with specific messages for each.</p>

diff --git a/src/main/java/com/smartsheet/api/internal/SheetResourcesImpl.java b/src/main/java/com/smartsheet/api/internal/SheetResourcesImpl.java
@@ -184,6 +184,22 @@ public SheetResourcesImpl(SmartsheetImpl smartsheet) {
         this.sheetSummary = new SheetSummaryResourcesImpl(smartsheet);
     }
 
+    /**
+     * List all sheets.
+     * <p>
+     * It mirrors to the following Smartsheet REST API method: GET /sheets
+     * @return A list of all sheets (note that an empty list will be returned if there are none).
+     * @throws IllegalArgumentException if any argument is null or empty string
+     * @throws InvalidRequestException if there is any problem with the REST API request
+     * @throws AuthorizationException if there is any problem with  the REST API authorization (access token)
+     * @throws ResourceNotFoundException if the resource cannot be found
+     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
+     * @throws SmartsheetException if there is any other error during the operation
+     */
+    public PagedResult<Sheet> listSheets() throws SmartsheetException {
+        return this.listSheets(null, null, null);
+    }
+
     /**
      * List all sheets.
      * <p>
@@ -376,6 +392,23 @@ public Sheet getSheet(
         return this.getResource(path, Sheet.class);
     }
 
+    /**
+     * <p>Get sheet by ID. Load all row and column data</p>
+     *
+     * @param sheetId id of the sheet to fetch
+     * @return the sheet resource (note that if there is no such resource, this method will throw
+     *     ResourceNotFoundException rather than returning null).
+     * @throws IllegalArgumentException if any argument is null or empty string
+     * @throws InvalidRequestException if there is any problem with the REST API request
+     * @throws AuthorizationException if there is any problem with  the REST API authorization (access token)
+     * @throws ResourceNotFoundException if the resource cannot be found
+     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
+     * @throws SmartsheetException if there is any other error during the operation
+     */
+    public Sheet getSheet(long sheetId) throws SmartsheetException {
+        return getSheet(sheetId, null, null, null, null, null, null, null, null, null);
+    }
+
     /**
      * Get a sheet as an Excel file.
      * <p>

diff --git a/src/main/java/com/smartsheet/api/internal/SheetRowResourcesImpl.java b/src/main/java/com/smartsheet/api/internal/SheetRowResourcesImpl.java
@@ -42,6 +42,7 @@
 import com.smartsheet.api.models.PartialRowUpdateResult;
 import com.smartsheet.api.models.Row;
 import com.smartsheet.api.models.RowEmail;
+import com.smartsheet.api.models.Sheet;
 import com.smartsheet.api.models.enums.ObjectExclusion;
 import com.smartsheet.api.models.enums.RowCopyInclusion;
 import com.smartsheet.api.models.enums.RowInclusion;
@@ -350,6 +351,72 @@ public List<Row> updateRows(
         return this.putAndReceiveList(path, rows, Row.class);
     }
 
+    /**
+     * <p>Helper method: Update a single cell</p>
+     *
+     * @param sheetId the sheet ID the cell should be written to
+     * @param cell the cell object to be written. Must include a rowId and columnId
+     * @return The returned Row object from the api
+     * @throws SmartsheetException the smartsheet exception
+     */
+    public Row updateCell(long sheetId, Cell cell) throws SmartsheetException {
+        if (cell.getRowId() == null || cell.getColumnId() == null) {
+            throw new SmartsheetException("Cell must include rowId and columnId");
+        }
+
+        Row updateRow = new Row();
+        updateRow.setCells(List.of(cell));
+        updateRow.setId(cell.getRowId());
+
+        List<Row> rows = updateRows(sheetId, List.of(updateRow));
+        return rows.isEmpty() ? null : rows.get(0);
+    }
+
+    /**
+     * <p>Helper method: Update a single with a string value</p>
+     * <p>NOTE: This method internally fetches the sheet. To avoid this step, fetch the sheet in
+     * advance and use the method by the same name</p>
+     *
+     * @param sheetId the sheet ID the cell should be written to
+     * @param rowIdx the row index of the cell (base 1 indexed)
+     * @param colIdx the column index of the cell (base 1 indexed)
+     * @param newValue the new value of the cell
+     * @return The returned Row object from the api
+     * @throws SmartsheetException the smartsheet exception
+     */
+    public Row updateCell(long sheetId, int rowIdx, int colIdx, String newValue) throws SmartsheetException {
+        Sheet sheet = smartsheet.sheetResources().getSheet(sheetId);
+        return updateCell(sheet, colIdx, rowIdx, newValue);
+    }
+
+    /**
+     * <p>Helper method: Update a single with a string value</p>
+     *
+     * @param sheet The sheet to update the cell in. Must include rowId and cell information
+     * @param rowIdx The row index of the cell (base 1 indexed)
+     * @param colIdx The column index of the cell (base 1 indexed)
+     * @param newValue The new value of the cell
+     * @return The returned Row object from the api
+     * @throws SmartsheetException the smartsheet exception
+     */
+    public Row updateCell(Sheet sheet, int rowIdx, int colIdx, String newValue) throws SmartsheetException {
+        Row row = sheet.getRowByRowNumber(rowIdx);
+        if (row == null) {
+            throw new SmartsheetException("Sheet does not contain row at index" + rowIdx);
+        }
+        long rowId = row.getId();
+        if (row.getCells().size() < colIdx) {
+            throw new SmartsheetException("Sheet does not contain column at index" + colIdx);
+        }
+        long colId = row.getCells().get(colIdx - 1).getColumnId();
+
+        Cell cell = new Cell();
+        cell.setColumnId(colId);
+        cell.setRowId(rowId);
+        cell.setValue(newValue);
+        return updateCell(sheet.getId(), cell);
+    }
+
     /**
      * Update rows, but allow partial success. The PartialRowUpdateResult will contain the successful
      * rows and those that failed, with specific messages for each.

diff --git a/src/sample/java/com/smartsheet/api/sample/Sample.java b/src/sample/java/com/smartsheet/api/sample/Sample.java
@@ -47,7 +47,7 @@ public static void main(String[] args) {
             Smartsheet smartsheet = SmartsheetFactory.createDefaultClient( /* "ll352u9jujauoqz4gstvsae05" */);
 
             // List all sheets
-            PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(null, null, null );
+            PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets();
             System.out.println("\nFound " + sheets.getTotalCount() + " sheets\n");
 
             Long sheetId = sheets.getData().get(0).getId();            // Default to first sheet
@@ -56,7 +56,7 @@ public static void main(String[] args) {
             // sheetId = 239236234L;
 
             // Load entire sheet
-            Sheet sheet = smartsheet.sheetResources().getSheet(sheetId, null, null, null, null, null, null, null);
+            Sheet sheet = smartsheet.sheetResources().getSheet(sheetId);
             List<Row> rows = sheet.getRows();
             System.out.println("\nLoaded sheet id " + sheetId + " with " + rows.size() + " rows, title: " + sheet.getName());
 

diff --git a/src/test/java/com/smartsheet/api/integrationtest/RowResourcesIT.java b/src/test/java/com/smartsheet/api/integrationtest/RowResourcesIT.java
@@ -346,4 +346,14 @@ public void testDeleteRows() throws SmartsheetException, IOException {
         deleteSheet(sheet.getId());
         deleteSheet(copyToSheet.getId());
     }
+
+    @Test
+    public void testUpdateSingleCell() throws Exception {
+        testAddRows();
+
+        smartsheet.sheetResources().rowResources().updateCell(sheet.getId(), 1, 1, "Updated Value");
+
+        Sheet checkSheet = smartsheet.sheetResources().getSheet(sheet.getId());
+        assertThat(checkSheet.getRows().get(0).getCells().get(0).getValue()).isEqualTo("Updated Value");
+    }
 }
diff --git a/src/test/java/com/smartsheet/api/integrationtest/SheetResourcesIT.java b/src/test/java/com/smartsheet/api/integrationtest/SheetResourcesIT.java
@@ -268,7 +268,7 @@ public void testCreateSheetInWorkspaceFromTemplate() throws SmartsheetException
     }
 
     public void testGetSheet() throws SmartsheetException, IOException {
-        Sheet sheet = smartsheet.sheetResources().getSheet(newSheetHome.getId(), null, null, null, null, null, null, null);
+        Sheet sheet = smartsheet.sheetResources().getSheet(newSheetHome.getId());
 
         assertThat(newSheetHome.getPermalink()).isEqualTo(sheet.getPermalink());
     }
@@ -369,7 +369,7 @@ public void testListSheets() throws SmartsheetException, IOException {
                 .setPage(1)
                 .build();
         PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(EnumSet.of(SourceInclusion.SOURCE), parameters);
-        smartsheet.sheetResources().listSheets(null, null);
+        smartsheet.sheetResources().listSheets();
 
         assertThat(sheets.getPageNumber()).isEqualTo(1);
     }

diff --git a/src/test/java/com/smartsheet/api/internal/SheetResourcesImplTest.java b/src/test/java/com/smartsheet/api/internal/SheetResourcesImplTest.java
@@ -105,7 +105,7 @@ void testListOrganizationSheets() throws SmartsheetException, IOException {
     void testGetSheet() throws SmartsheetException, IOException {
 
         server.setResponseBody(new File("src/test/resources/getSheet.json"));
-        Sheet sheet = sheetResource.getSheet(123123L, null, null, null, null, null, null, null);
+        Sheet sheet = sheetResource.getSheet(123123L);
         assertThat(sheet.getColumns()).hasSize(9);
         assertThat(sheet.getRows()).isEmpty();
 
@@ -135,7 +135,7 @@ void testGetSheet() throws SmartsheetException, IOException {
     void testGetSheetWithFormat() throws SmartsheetException, IOException {
 
         server.setResponseBody(new File("src/test/resources/getSheetWithFormat.json"));
-        Sheet sheet = sheetResource.getSheet(123123L, null, null, null, null, null, null, null);
+        Sheet sheet = sheetResource.getSheet(123123L);
 
         assertThat(sheet.getColumnByIndex(0).getFormat()).isNotNull();
         assertThat(sheet.getColumnByIndex(0).getFormat().getVerticalAlignment()).isEqualTo(VerticalAlignment.TOP);

diff --git a/src/test/java/com/smartsheet/api/sdktest/RowTest.java b/src/test/java/com/smartsheet/api/sdktest/RowTest.java
@@ -39,7 +39,7 @@ class RowTest {
     @Test
     void ListSheets_NoParams() throws SmartsheetException {
         Smartsheet ss = HelperFunctions.SetupClient("List Sheets - No Params");
-        PagedResult<Sheet> sheets = ss.sheetResources().listSheets(null, null, null);
+        PagedResult<Sheet> sheets = ss.sheetResources().listSheets();
         assertThat(sheets.getData().get(0).getName()).isEqualTo("Copy of Sample Sheet");
     }
 

diff --git a/src/test/java/com/smartsheet/api/sdktest/SheetTest.java b/src/test/java/com/smartsheet/api/sdktest/SheetTest.java
@@ -34,7 +34,7 @@ class SheetTest {
     @Test
     void listSheets_NoParams() throws SmartsheetException {
         Smartsheet ss = HelperFunctions.SetupClient("List Sheets - No Params");
-        PagedResult<Sheet> sheets = ss.sheetResources().listSheets(null, null, null);
+        PagedResult<Sheet> sheets = ss.sheetResources().listSheets();
         assertThat(sheets.getData().get(0).getName()).isEqualTo("Copy of Sample Sheet");
     }