Documentation

Author: labkey-nicka

src/org/labkey/remoteapi/query/SaveRowsApiCommand.java

@@ -7,6 +7,55 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Command for executing multiple data modification operations (insert, update, delete) in a single request
+ * to a LabKey Server. This command allows batching multiple operations together, optionally in a transaction.
+ * <p>
+ * All data exposed from a LabKey Server is organized into schemas containing queries. Each command in a batch
+ * specifies the schema name (e.g., 'lists' or 'study') and query name (e.g., 'People' or 'Samples') to operate on.
+ * <p>
+ * The command supports several features:
+ * <ul>
+ *     <li>Multiple operations (insert, update, delete) in a single request</li>
+ *     <li>Optional transaction support to ensure all-or-nothing execution</li>
+ *     <li>Validation-only mode to check operations without making changes</li>
+ *     <li>Audit trail support with configurable detail levels</li>
+ *     <li>Custom audit comments for tracking changes</li>
+ * </ul>
+ * <p>
+ * Example usage:
+ * <pre><code>
+ * ApiKeyCredentialsProvider credentials = new ApiKeyCredentialsProvider("xxx");
+ * Connection conn = new Connection("http://localhost:8080", credentials);
+ * SaveRowsApiCommand saveCmd = new SaveRowsApiCommand();
+ *
+ * // Add new gene annotations
+ * saveCmd.addCommand(new Command(CommandType.Insert, "genome", "GeneAnnotations",
+ *     List.of(
+ *         Map.of("name", "p53 binding site", "geneName", "TP53", "start", 1000, "end", 1020),
+ *         Map.of("name", "TATA box", "geneName", "BRCA1", "start", 2500, "end", 2506)
+ *     )));
+ *
+ * // Update annotation positions
+ * Command updateCmd = new Command(CommandType.Update, "genome", "GeneAnnotations",
+ *     List.of(Map.of(
+ *         "name", "Promoter region",
+ *         "geneName", "EGFR",
+ *         "start", 5000,
+ *         "end", 5500
+ *     )));
+ * updateCmd.setAuditBehavior(SaveRowsCommand.AuditBehavior.DETAILED);
+ * updateCmd.setAuditUserComment("Updated promoter region coordinates based on new assembly");
+ * saveCmd.addCommand(updateCmd);
+ *
+ * // Delete obsolete annotation
+ * saveCmd.addCommand(new Command(CommandType.Delete, "genome", "GeneAnnotations",
+ *     List.of(Map.of("name", "Putative enhancer", "geneName", "MYC"))));
+ *
+ * // Execute all commands in a transaction
+ * SaveRowsApiResponse response = saveCmd.execute(conn, "GenomeProject");
+ * </code></pre>
+ */
 public class SaveRowsApiCommand extends PostCommand<SaveRowsApiResponse>
 {
     private final List<Command> _commands = new ArrayList<>();

src/org/labkey/remoteapi/query/SaveRowsApiResponse.java

@@ -9,6 +9,59 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Response object for the {@link SaveRowsApiCommand}, containing results of batch operations executed on the server.
+ * This response provides details about the success or failure of each command in the batch, including:
+ * <ul>
+ *     <li>Whether the transaction was committed</li>
+ *     <li>Number of errors encountered</li>
+ *     <li>Detailed results for each command executed</li>
+ * </ul>
+ * <p>
+ * Example usage:
+ * <pre><code>
+ * SaveRowsApiCommand cmd = new SaveRowsApiCommand();
+ * // Add commands to insert/update/delete gene annotations...
+ * SaveRowsApiResponse response = cmd.execute(connection, "GenomeProject");
+ *
+ * if (response.isCommitted())
+ * {
+ *     for (SaveRowsApiResponse.Result result : response.getResults())
+ *     {
+ *         System.out.println(String.format(
+ *             "%s operation affected %d rows in %s.%s",
+ *             result.getCommand(),
+ *             result.getRowsAffected(),
+ *             result.getSchemaName(),
+ *             result.getQueryName()
+ *         ));
+ *
+ *         // For detailed examination of affected rows
+ *         for (Map<String, Object> row : result.getRows())
+ *         {
+ *             System.out.println(String.format(
+ *                 "Gene %s annotation at position %d-%d",
+ *                 row.get("geneName"),
+ *                 row.get("start"),
+ *                 row.get("end")
+ *             ));
+ *         }
+ *
+ *         // Check if operation was audited
+ *         if (result.getTransactionAuditId() > 0)
+ *         {
+ *             System.out.println("Audit record created with ID: " +
+ *                 result.getTransactionAuditId());
+ *         }
+ *     }
+ * }
+ * else
+ * {
+ *     System.out.println("Transaction failed with " +
+ *         response.getErrorCount() + " errors");
+ * }
+ * </code></pre>
+ */
 public class SaveRowsApiResponse extends CommandResponse
 {
     private final boolean _committed;

src/org/labkey/remoteapi/test/SaveRowsApiDemo.java

@@ -22,10 +22,11 @@ public class SaveRowsApiDemo
 {
     public static void main(String[] args) throws Exception
     {
-        String folderPath = "SaveRowsCommandDemo";
+        String folderPath = "SaveRowsApiDemo";
         String schemaName = "lists";
         String queryName = "Players";
 
+        // Furnish your own API key
         ApiKeyCredentialsProvider credentials = new ApiKeyCredentialsProvider("xxx");
         Connection conn = new Connection("http://localhost:8080", credentials);