org.labkey.remoteapi.query

## Class SaveRowsCommand

- java.lang.Object
- - org.labkey.remoteapi.Command<ResponseType>
  - - org.labkey.remoteapi.PostCommand<SaveRowsResponse>
    - - org.labkey.remoteapi.query.SaveRowsCommand

- Direct Known Subclasses:
    DeleteRowsCommand, InsertRowsCommand, UpdateRowsCommand

      public abstract class SaveRowsCommand
      extends PostCommand<SaveRowsResponse>

  Base class for commands that make changes to rows exposed from a given query in a given schema. Clients should use `UpdateRowsCommand`, `InsertRowsCommand` or `DeleteRowsCommand` and not this class directly.

  All three of these sub-classes post similar JSON to the server, so this class does all the common work. The client must supply three things: the schemaName, the queryName and an array of 'rows' (i.e. Maps). The rows are added via the `addRow(Map)` or `setRows(List)` methods.

  All data exposed from the LabKey Server is organized into a set of queries contained in a set of schemas. A schema is simply a group of queries, identified by a name (e.g., 'lists' or 'study'). A query is particular table or view within that schema (e.g., 'People' or 'Peptides'). Currently, clients may update rows in base tables only, and not in joined views. Therefore the query name must be the name of a table in the schema.

  To view the schemas and queries exposed in a given folder, add a Query web part to your portal page and choose the option "Show the list of tables in this schema" in the part configuration page. Alternatively, if it is exposed, click on the Query tab across the top of the main part of the page.

  Examples:

        // May need to add CONTEXT_PATH for dev instances
        Connection cn = new Connection("http://localhost:8080", user, password);

        //Insert Rows Command
        InsertRowsCommand cmd = new InsertRowsCommand("lists", "People");

        Map<String,Object> row = new HashMap<String,Object>();
        row.put("FirstName", "Insert");
        row.put("LastName", "Test");

        cmd.addRow(row); //can add multiple rows to insert many at once
        SaveRowsResponse resp = cmd.execute(cn, "PROJECT_NAME");

        //get the newly-assigned primary key value from the first return row
        int newKey = resp.getRows().get(0).get("Key");

        //Update Rows Command
        UpdateRowsCommand cmdUpd = new UpdateRowsCommand("lists", "People");
        row = new HashMap<String,Object>();
        row.put("Key", newKey);
        row.put("LastName", "Test UPDATED");
        cmdUpd.addRow(row);
        resp = cmdUpd.execute(cn, "PROJECT_NAME");

        //Delete Rows Command
        DeleteRowsCommand cmdDel = new DeleteRowsCommand("lists", "People");
        row = new HashMap<String,Object>();
        row.put("Key", newKey);
        cmdDel.addRow(row);
        resp = cmdDel.execute(cn, "PROJECT_NAME");

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.labkey.remoteapi.Command

      `Command.CommonParameters, Command.Response`

  - ### Field Summary

    - ### Fields inherited from class org.labkey.remoteapi.Command

      `CONTENT_TYPE_JSON`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SaveRowsCommand(SaveRowsCommand source)`
    `protected` | `SaveRowsCommand(java.lang.String schemaName, java.lang.String queryName, java.lang.String actionName)` Constructs a new SaveRowsCommand for a given schema, query and action name.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRow(java.util.Map<java.lang.String,java.lang.Object> row)` Adds a row to the list of rows to be sent to the server.
    `abstract SaveRowsCommand` | `copy()` Returns a copy of this object.
    `protected SaveRowsResponse` | `createResponse(java.lang.String text, int status, java.lang.String contentType, org.json.simple.JSONObject json)` Creates an instance of the response class, initialized with the response text, the HTTP status code, and parsed JSONObject.
    `java.util.Map<java.lang.String,java.lang.Object>` | `getExtraContext()` Gets the additional extra context.
    `org.json.simple.JSONObject` | `getJsonObject()` Dynamically builds the JSON object to send based on the current schema name, query name and rows list.
    `java.lang.String` | `getQueryName()` Returns the query name
    `java.util.List<java.util.Map<java.lang.String,java.lang.Object>>` | `getRows()` Returns the current list of 'rows' (i.e., Maps) that will be sent to the server.
    `java.lang.String` | `getSchemaName()` Returns the schema name.
    `void` | `setExtraContext(java.util.Map<java.lang.String,java.lang.Object> extraContext)` Sets the additional extra context.
    `void` | `setQueryName(java.lang.String queryName)` Sets a new query name to update
    `void` | `setRows(java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)` Sets the list of 'rows' (i.e., Maps) to be sent to the server.
    `void` | `setSchemaName(java.lang.String schemaName)` Sets the schema name

    - ### Methods inherited from class org.labkey.remoteapi.PostCommand

      `createRequest, setJsonObject`

    - ### Methods inherited from class org.labkey.remoteapi.Command

      `_execute, execute, getActionName, getActionUrl, getControllerName, getHttpRequest, getParameters, getParamValueAsString, getQueryString, getRequiredVersion, getTimeout, setParameters, setRequiredVersion, setTimeout`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SaveRowsCommand

          protected SaveRowsCommand(java.lang.String schemaName,
                                    java.lang.String queryName,
                                    java.lang.String actionName)

      Constructs a new SaveRowsCommand for a given schema, query and action name.
      Parameters:
        `schemaName` - The schema name.
        `queryName` - The query name.
        `actionName` - The action name to call (supplied by the derived class).

    - #### SaveRowsCommand

          protected SaveRowsCommand(SaveRowsCommand source)

  - ### Method Detail

    - #### getSchemaName

          public java.lang.String getSchemaName()

      Returns the schema name.
      Returns:
        The schema name.

    - #### setSchemaName

          public void setSchemaName(java.lang.String schemaName)

      Sets the schema name
      Parameters:
        `schemaName` - The new schema name.

    - #### getQueryName

          public java.lang.String getQueryName()

      Returns the query name
      Returns:
        the query name.

    - #### setQueryName

          public void setQueryName(java.lang.String queryName)

      Sets a new query name to update
      Parameters:
        `queryName` - the query name.

    - #### getExtraContext

          public java.util.Map<java.lang.String,java.lang.Object> getExtraContext()

      Gets the additional extra context.
      Returns:
        the extra context.

    - #### setExtraContext

          public void setExtraContext(java.util.Map<java.lang.String,java.lang.Object> extraContext)

      Sets the additional extra context.
      Parameters:
        `extraContext` - The extra context.

    - #### getRows

          public java.util.List<java.util.Map<java.lang.String,java.lang.Object>> getRows()

      Returns the current list of 'rows' (i.e., Maps) that will be sent to the server.
      Returns:
        The list of rows.

    - #### setRows

          public void setRows(java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)

      Sets the list of 'rows' (i.e., Maps) to be sent to the server.
      Parameters:
        `rows` - The rows to send

    - #### addRow

          public void addRow(java.util.Map<java.lang.String,java.lang.Object> row)

      Adds a row to the list of rows to be sent to the server.
      Parameters:
        `row` - The row to add

    - #### getJsonObject

          public org.json.simple.JSONObject getJsonObject()

      Dynamically builds the JSON object to send based on the current schema name, query name and rows list.
      Overrides:
        `getJsonObject` in class `PostCommand<SaveRowsResponse>`
      Returns:
        The JSON object to send.

    - #### createResponse

          protected SaveRowsResponse createResponse(java.lang.String text,
                                                    int status,
                                                    java.lang.String contentType,
                                                    org.json.simple.JSONObject json)

      Description copied from class: `Command`
      Creates an instance of the response class, initialized with the response text, the HTTP status code, and parsed JSONObject.

      Override this method to create an instance of a different class that extends CommandResponse

      Overrides:
        `createResponse` in class `Command<SaveRowsResponse>`
      Parameters:
        `text` - The response text from the server.
        `status` - The HTTP status code.
        `contentType` - The Content-Type header value.
        `json` - The parsed JSONObject (or null if no JSON was returned).
      Returns:
        An instance of the response object.

    - #### copy

          public abstract SaveRowsCommand copy()

      Description copied from class: `Command`
      Returns a copy of this object. Derived classes should override this to copy their own data members
      Overrides:
        `copy` in class `PostCommand<SaveRowsResponse>`
      Returns:
        A copy of this object