[ignite-3] branch ignite-15792 created (now 4d97e22)

[am...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

amashenkov pushed a change to branch ignite-15792
in repository https://gitbox.apache.org/repos/asf/ignite-3.git.


      at 4d97e22  Add README.md for mappers.

This branch includes the following new commits:

     new 4d97e22  Add README.md for mappers.

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[ignite-3] 01/01: Add README.md for mappers.

[am...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

amashenkov pushed a commit to branch ignite-15792
in repository https://gitbox.apache.org/repos/asf/ignite-3.git

commit 4d97e22dd1a4dbd847ffb2b7ea03c1b6d3916a6e
Author: Andrew Mashenkov <an...@gmail.com>
AuthorDate: Mon Dec 6 19:38:37 2021 +0300

    Add README.md for mappers.
---
 .../java/org/apache/ignite/table/mapper/README.md  | 44 ++++++++++++++++++++++
 modules/schema/README.md                           | 19 ++++++++++
 2 files changed, 63 insertions(+)

diff --git a/modules/api/src/main/java/org/apache/ignite/table/mapper/README.md b/modules/api/src/main/java/org/apache/ignite/table/mapper/README.md
new file mode 100644
index 0000000..8ed37c6
--- /dev/null
+++ b/modules/api/src/main/java/org/apache/ignite/table/mapper/README.md
@@ -0,0 +1,44 @@
+# Mappers
+
+In addition to binary views, which uses Tuple as key-value/record types, there are generic views, which allow using arbitrary
+user classes as key-value/record types. These views require a custom mapping for binding objects or object fields with
+the table columns in one-to-one manner.
+
+[Mapper API](Mapper.java) provides a number of shortcut method for most simple cases, and a [MapperBuilder](MapperBuilder.java) 
+for more complex ones. In normal use, there is no need to implement a custom Mapper.
+
+Mapper API allows to map either a whole object to a one column, or an object fields to the columns.
+In general, a field maps to a column with the same name unless the mapper defines another name.
+In both cases, it is possible to specify [TypeConverter](TypeConverter.java) for converting data to/from a column compatible type.
+If the object type doesn't match the column type, then converter for the column is mandatory and must be set by the user via mapper.
+
+User objects are converted into binary form using mapper and converters on the client-side, and neither user object, nor mapper object,
+nor converter object, nor their code is transferred among the nodes. This allows to use different classes/mappers and/or their versions 
+on different nodes and provide better flexibility for maintaining user application on the top of Ignite.
+
+In case of one column mapping, when key or value contains exactly one column, then the column can be detected at runtime,
+thus `Mapper.of(Class)` method without specifying exact column can be used for nativly supported types (such as Long, LocalDate, UUID and etc).
+If an user POJO is provided, then Ignite will try to create default mapping for the object fields. 
+ 
+##Single column mapping.
+* `Mapper.of(Class)` - maps natively supported type to a single available column. It is safe to use for keys. However, be carefull using it for values as if may become invalid once a new column will be added.
+* `Mapper.of(Class, String)` - safer than above because column name is specified explicitly.
+* `Mapper.of(Class, String , TypeConverter)` - same with type converter.
+
+##Multi-column mapping.
+* `Mapper.of(Class)` - when passed a type, which has no native support, tries to map object fields to the columns with same names. 
+* `Mapper.of(Class, String, String,  String...)` - maps class fields to the columns regarding (field_name, column_name) pairs in vararg.  
+
+##MapperBuilder approach.
+
+* `Mapper.builder(Class)` - creates a mapper builder for the class.
+
+[Mapper builder](MapperBuilder.java) class provides method for more complex cases, and allows to set converters for individual columns.
+Builder object is not reusable.
+
+* `MapperBuilder.map(String, String,  String...)` - maps class fields to the columns regarding (field_name, column_name) pairs in vararg.
+* `MapperBuilder.map(Class, String)` - defines a converter for given column.
+* `MapperBuilder.map(String, String, Class)` - maps the field to the column with type converter, is a shortcut for 
+`MapperBuilder.map(field, column).converter(Converter.class, column)`
+* `MapperBuilder.automap()` - forces default mapping strategy for omitted field-column pair, and maps fields to columns with same names.
+ Builder ignores missed fields/columnsm unless this method is called.  
diff --git a/modules/schema/README.md b/modules/schema/README.md
index aba4ff3..86f2cac 100644
--- a/modules/schema/README.md
+++ b/modules/schema/README.md
@@ -29,6 +29,25 @@ is non-ambiguous (a type upcast, e.g. Int8 → Int16, or by means of a certain e
 the `CAST` expression).
  
 ### Data Layout
+We assume that there is exactly one valid binary representation for each key, thus binary keys representations can be 
+safely compared instead of keys themselves avoiding unnecessary deserialization. To achieve that, key columns are fixed 
+at a time of table created, and key columns can't be added or removed. All the key columns values must be provided 
+for a table operation, to resolve unambiguity of 'null or absent' column.     
+
 Data layout is documentation can be found [here](src/main/java/org/apache/ignite/internal/schema/README.md)
 
 ## Object-to-schema mapping
+
+Mappers API provides two interfaces for two different cases: 
+* [OneColumnMapper](../api/src/main/java/org/apache/ignite/table/mapper/OneColumnMapper.java) for the case, 
+when a whole object is mapped to a one column. 
+* [PojoMapper](../api/src/main/java/org/apache/ignite/table/mapper/OneColumnMapper.java) for the case, then object fields are
+mapped to columns.
+
+Mappers and Type converters designed as node specific stuff and never transferred among nodes.
+All the machinery translating user object to an intermediate (binary) representation is applied on the client side. 
+ 
+Mapper is used only for creating marshaller for user objects every time a schema has changed or Record/KeyValue view instance is created.
+**For better performance, a marshaller code can be generated and/or marshaller instance can be cached and reused.
+ 
+See [Mapper API](../api/src/main/java/org/apache/ignite/table/mapper/README.md) for details.
\ No newline at end of file