com.smartgwt.client.types

## Enum RESTRequestFormat

- java.lang.Object
- - java.lang.Enum<RESTRequestFormat>
  - - com.smartgwt.client.types.RESTRequestFormat

- All Implemented Interfaces:
    ValueEnum, java.io.Serializable, java.lang.Comparable<RESTRequestFormat>

      public enum RESTRequestFormat
      extends java.lang.Enum<RESTRequestFormat>
      implements ValueEnum

  Indicates the request format to be used for a REST operation. Is only applicable to `RestConnector DataSources`. Note for all of these `RESTRequestFormat` options, only simple key-value criteria are supported; to handle `AdvancedCriteria`, you can use a `requestTemplate`, or subclass `com.isomorphic.dataSource.RestConnector` and override the `applyValuesOrCriteriaToRequest()` method.

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant and Description
    `JSON` Indicates that context is provided to the target REST service by providing a block of JSON-encoded text in the body of the HTTP request sent to the REST server.
    `PARAMS` Indicates that context is provided to the target REST service by setting parameter values in the URL.
    `XML` Indicates that context is provided to the target REST service by providing a block of XML text in the body of the HTTP request sent to the REST server.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getValue()`
    `static RESTRequestFormat` | `valueOf(java.lang.String name)` Returns the enum constant of this type with the specified name.
    `static RESTRequestFormat[]` | `values()` Returns an array containing the constants of this enum type, in the order they are declared.

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

      `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Enum Constant Detail

    - #### PARAMS

          public static final RESTRequestFormat PARAMS

      Indicates that context is provided to the target REST service by setting parameter values in the URL. With this request format, the `DSRequest`'s values or criteria will be added to the `target dataURL` as standard HTTP parameters values as follows:
      - For "add" and "update" requests the "values" will be added to the target URL (see the server-side Javadoc for `DSRequest.getValues()`)
      - For "fetch" and "remove" requests, where the concept of "values" doesn't make sense, the "criteria" will be added to the target URL (see the server-side Javadoc for `DSRequest.getCriteria()`)
      So if we had a fetch request that specified criteria like this:

            {countryCode: "US", stateCode: "CA"}

      and a `dataURL` like this:

            https://somerestservice.com/customer/fetch

      we would end up with a target URL like this:

            https://somerestservice.com/customer/fetch?countryCode=US&stateCode=CA

      Also, note that any explicitly declared `params` will also be added to the target URL as standard HTTP parameters, as well as the request values/criteria (if there are any name collisions, the request values/criteria take precedence).

      This format is often used to supply criteria to "fetch" operations, and primary-key values to "remove" operations. However, this is by no means a universal approach; different REST services adopt different approaches, there is no generally-accepted "right way" to handle things

      It is possible to suppress this automatic mapping - see `DataSource.suppressAutoMappings`

      If this enumerated value is used in a `Component XML` file or server-side DataSource descriptor (.ds.xml file), use the value "params".

    - #### JSON

          public static final RESTRequestFormat JSON

      Indicates that context is provided to the target REST service by providing a block of JSON-encoded text in the body of the HTTP request sent to the REST server. With this request format, `RestConnector` will render an incoming `DSRequest`'s values or criteria as a JSON object; for "add" and "update" requests, the "values" will be used, and for "fetch" and "remove" operations, the criteria will be used (see the server-side Javadoc for `DSRequest.getCriteria()`).

      So if we had an add request with the following record:

            {
            customerId: 7023,
            customerName: "Bay Financials inc",
            city: "San Francisco",
            countryCode: "US",
            stateCode: "CA"
            }

      those values would be included, in strict JSON form, in the body of the HTTP request that `RestConnector` sends to the REST webservice:

            {"customerId": 7023,"customerName": "Bay Financials inc",
            "city: "San Francisco","countryCode": "US", "stateCode": "CA"}

      This format is most often used when you need to supply more extensive amounts of data, like entire records to "add" and "update" operations. However, as mentioned above, this is by no means a universal approach, and some REST services use URL parameters even when specifying entire records of data. Also, some REST services use XML rather than JSON

      Note, if there is a `requestTemplate` in force, we use that to drive the content and format of the generated JSON block

      If this enumerated value is used in a `Component XML` file or server-side DataSource descriptor (.ds.xml file), use the value "json".

    - #### XML

          public static final RESTRequestFormat XML

      Indicates that context is provided to the target REST service by providing a block of XML text in the body of the HTTP request sent to the REST server. With this request format, `RestConnector` will render an incoming `DSRequest`'s values or criteria as a snippet of XML text; for "add" and "update" requests, the "values" will be used, and for "fetch" and "remove" operations, the criteria will be used (see the server-side Javadoc for `DSRequest.getCriteria()`). The name of the enclosing tag is specified in `DataSource.xmlTag`.

      So if we had an add request with the following record:

            {
            customerId: 7023,
            customerName: "Bay Financials inc",
            city: "San Francisco",
            countryCode: "US",
            stateCode: "CA"
            }

      those values would be included in the body of the HTTP request that `RestConnector` sends to the REST webservice (assuming the `xmlTag` is "customer"):

            <customer>
            <customerId>7023</customerId>
            <customerName>Bay Financials inc"</customerName>
            <city>San Francisco</city>
            <countryCode>US</countryCode>
            <stateCode>CA"</stateCode>
            </customer>

      Note, if there is a `requestTemplate` in force, we use that to drive the content and format of the generated XML

      If this enumerated value is used in a `Component XML` file or server-side DataSource descriptor (.ds.xml file), use the value "xml".

  - ### Method Detail

    - #### values

          public static RESTRequestFormat[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (RESTRequestFormat c : RESTRequestFormat.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static RESTRequestFormat valueOf(java.lang.String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
        `name` - the name of the enum constant to be returned.
      Returns:
        the enum constant with the specified name
      Throws:
        `java.lang.IllegalArgumentException` - if this enum type has no constant with the specified name
        `java.lang.NullPointerException` - if the argument is null

    - #### getValue

          public java.lang.String getValue()

      Specified by:
        `getValue` in interface `ValueEnum`