[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