This is an automated email from the ASF dual-hosted git repository. dmagda pushed a commit to branch IGNITE-7595 in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push: new 5f81c37 IGNITE-12977 Documentation. (#8245) 5f81c37 is described below commit 5f81c3752f4c04329da2b9790573fc0d7ec043da Author: Pavel Pereslegin <xxt...@gmail.com> AuthorDate: Fri Sep 18 00:27:50 2020 +0300 IGNITE-12977 Documentation. (#8245) * IGNITE-12977 Documentation. * IGNITE-12977 Docs (wip). * IGNITE-12977 Docs (wip). * IGNITE-12977 Review notes lang fixes. * IGNITE-12977 Use table to display definition example. --- docs/_docs/restapi.adoc | 90 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 2 deletions(-) diff --git a/docs/_docs/restapi.adoc b/docs/_docs/restapi.adoc index 3a60408..000e626 100644 --- a/docs/_docs/restapi.adoc +++ b/docs/_docs/restapi.adoc @@ -169,10 +169,13 @@ To set a custom expire time, set the system variable: `IGNITE_REST_SESSION_TIMEO ==== == Data Types -The REST API also supports Java built-in types for put/get operations via `keyType` and `valueType` optional parameters. -Note that unless one of the below mentioned types are explicitly specified, the REST protocol exchanges the key-value data in `String` format. +The REST API also supports <<Java built-in types>> and <<Custom user defined types>> for put/get operations via `keyType` and `valueType` optional parameters. + +Note that unless one of the types mentioned below is explicitly specified, the REST protocol will exchange the key-value data in `String` format. This means that the data is stored and retrieved to/from the cluster as a `String`. +=== Java built-in types + [width="100%", cols="50%,50%"] |======= | REST KeyType/ValueType | Corresponding Java Type @@ -240,6 +243,71 @@ Similarly, the `get` command with `keyType=int` and `valueType=date` would be: http://[host]:[port]/ignite?cmd=get&key=1&cacheName=myCache&keyType=int&valueType=date ---- +=== Custom user defined types + +For custom objects, the JSON format is used. For example, we can work with the following object using the REST API: +[source,javascript] + { + "uid": "7e51118b-eb15-4373-b57f-4984cb9cd7ac", + "name": "John Doe", + "organization": 5678901, + "married": false, + "salary": 156.1 + } + +The following request puts this object into the cache named 'testCache' as a value with a type name `Person` and a key `1`. + + http://[host]:[port]/ignite?cacheName=testCache&cmd=put&keyType=int&key=1&valueType=Person&val=%7B%0A+++++%22uid%22%3A+%227e51118b-eb15-4373-b57f-4984cb9cd7ac%22%2C%0A+++++%22name%22%3A+%22John+Doe%22%2C%0A+++++%22organization%22%3A+5678901%2C%0A+++++%22married%22%3A+false%2C%0A+++++%22salary%22%3A+156.1%0A++%7D& + +On the server side, the JSON value from this request will be converted to link:/docs/data-modeling/data-modeling#binary-object-format[binary object]. Field types are resolved in the following order: + +* If the type name is a `Java class` available on the server, the class field types with corresponding names will be used for resolving JSON object field types. +* If the type name is of a `query entity` type, the field types will be resolved according to the field type defined in the `query entity`. +* Otherwise, the field types will be resolved according to regular JSON types. + +For example, if there is no definition of the "Person" type on the server, the fields will be converted in accordance with the standard JSON types: +[source,javascript] +"uid": "7e51118b-eb15-4373-b57f-4984cb9cd7ac", // string +"name": "John Doe", // string +"organization": 5678901, // int +"married": false, // boolean +"salary": 156.1 // double + +If the `query entity` is set or `Java class` "Person" is loaded on the server. +[%header, cols="2"] +|=== +|Query entity|Java class +a|[source,xml] +<bean class="org.apache.ignite.cache.QueryEntity"> + <property name="keyType" value="java.lang.Integer"/> + <property name="valueType" value="Person"/> + <property name="fields"> + <map> + <entry key="uid" value="java.util.UUID"/> + <entry key="name" value="java.lang.String"/> + <entry key="organization" value="java.lang.Long"/> + <entry key="married" value="java.lang.Boolean"/> + <entry key="salary" value="java.lang.Float"/> + </map> + </property> +</bean> +a|[source,java] +class Person { + UUID uid; + String name; + long organization; + boolean married; + float salary; +} +|=== + +The fields of the object will be of the following types: +[source,javascript] + "uid": "7e51118b-eb15-4373-b57f-4984cb9cd7ac", // UUID + "name": "John Doe", // string + "organization": 5678901, // long + "married": false, // boolean + "salary": 156.1 // float == Returned Value The HTTP REST request returns a JSON object which has a similar structure for each command: @@ -2559,6 +2627,12 @@ http://host:port/ignite?cmd=qryexe&type={type}&pageSize={pageSize}&cacheName={ca | | Encoding sql query | `salary+%3E+%3F+and+salary+%3C%3D+%3F` + +|`keepBinary` +| boolean +| Yes +| do not deserialize link:/docs/data-modeling/data-modeling#binary-object-format[binary objects], `false` by default +|`true` |======= *Response:*:: @@ -2622,6 +2696,12 @@ http://host:port/ignite?cmd=qryfldexe&pageSize=10&cacheName={cacheName}&qry={qry | | Encoding sql fields query. |`select+firstName%2C+lastName+from+Person` + +|`keepBinary` +| boolean +| Yes +| do not deserialize link:/docs/data-modeling/data-modeling#binary-object-format[binary objects], `false` by default +|`true` |======= *Response:*:: @@ -2692,6 +2772,12 @@ http://host:port/ignite?cmd=qryscanexe&pageSize={pageSize}&cacheName={cacheName} | Yes | Predicate class name for scan query. Class should implement `IgniteBiPredicate` interface. | `org.apache.ignite.filters.PersonPredicate` + +|`keepBinary` +| boolean +| Yes +| do not deserialize link:/docs/data-modeling/data-modeling#binary-object-format[binary objects], `false` by default +|`true` |======= *Response:*::