Кодирование таблиц данных

Любая таблица данных может кодироваться в или декодироваться из:

  • Строки Юникода

  • Байтового массива

Кодирование и декодирование строк часто используется для программного манипулирования таблицами данных, например, через Java SDK или .NET API. Строковое представление табличных форматов также часто используется для компактного и удобного для чтения отображения данных.

Кодирование и декодирование байтовых массивов используется для переноса таблиц данных по сети при помощи Коммуникационного протокола SberMobile или хранения их в базе данных SberMobile Server.

Кодирование байтовых массивов

Перекодирование таблицы данных в байтовый массив проходит в два этапа:

  • Во-первых, таблица данных кодируется в строку Юникода

  • Во-вторых, строка результата кодируется в байтовый массив при помощи кодировки UTF-8. См. документацию по UTF-8 (например, Статья в Wikipedia по UTF-8) для более подробного ознакомления.

Концепция кодирования строк

В целом, таблица данных и её различные части закодированы в строку как ряд элементов следующего формата:

<[element_name=]element_value>

Имя и значение могут включать любой символ, за исключением тех, которые использует протокол взаимодействия SberMobilel или тех, которые используются для кодирования самого элемента. Значение элемента может быть закодированным списком вложенных элементов.

Кодирование таблицы

Здесь представлен формат для закодированной таблицы данных:

<F=record_format>[<I=>][<R=record>][<R=record>]…

Имя элемента

Значение элемента

F

Дескриптор формата таблицы, определяющий имена и типы всех колонок в таблице данных или других свойств таблицы. О его кодировании говорится здесь.

D

ID формата таблицы. Более поробно см. раздел кэширование формата.

I

Элемент для проверки. Если данный элемент найден в таблице данных, вся таблица считается неверной. Когда SberMobile Server запрашивает значение переменной от агента, агент сначала подтверждает запрос, а затем начинает опрос записей с аппаратного устройства. В это время сервер "думает", что он получает полную и правильную таблицу.

Если в этот момент возникает внезапный разрыв связи между агентом и устройством, и по какой-то причине агент не получает данные, которые он должен получать от аппаратного устройства, агент вставляет проверочный элемент в таблицу данных, отправляемую серверу. Этот элемент сообщает серверу, что он не может полностью получить все эти данные. После получения этого элемента сервер "знает", что операция не может быть полностью завершена.

R

Запись таблицы данных. Записи закодированы одна за другой. Формат закодированных записей описан ниже.

T

Временная метка таблицы данных. Обычно указывает на время создания/получения самой таблицы данных или выборки данных, которую она представляет. Временная метка кодируется в строку как количество миллисекунд с начала отсчета времени (1 января 1970 г.).

Q

Качество таблицы. Оно объясняет, насколько надежна выборка данных, представленная таблицей данных. Качество является 32-битным подписанным целым значением, закодированным в строку.

Пример: <F=<<IP><S><F=C>><M=1><X=1>><R=<192.168.1.88>>

Этот пример показывает, что формат закодированной таблицы данных определяет одно поле строки, именуемое "IP", и что он содержит одну запись со значением "192.168.1.88". См. дополнительную информацию о записи и кодировке формата ниже.

Кодировка формата таблицы

record_format включён в каждую таблицу данных, даже если она пустая. Кодировка выглядит следующим образом:

<field_format><field_format>…[<F=flags>][<V=table_validators>][<R=record_validators>][M=min_records][X=max_records][<B=bindings>][<N=naming_expression>]

Элементы без идентификаторов (как показано в примере ранее <field_format>) считаются дескрипторами закодированных форматов полей таблиц. Дескрипторы формата полей закодированы один за другим, начиная с самого первого поля.

Имя элемента

Значение элемента

F

Отсутствие или комбинация следующих флагов:

“R” (Перемещаемый (Reorderable)) - указывает, что пользователи SberMobile могут перемещать во время редактирования ряды данной таблицы

“U” (Неизменяемый (Unresizable)) - указывает, что пользователи не могут добавлять/удалять ряды во время редактирования таблицы.

V

Валидаторы таблиц, которые позволяют выполнять комплексное подтверждение всей таблицы.  

R

Валидаторы записей, которые используются для подтверждения каждой записи.

B

Привязки таблиц.

M

Минимальное разрешённое количество записей в таблице.

X

Максимальное разрешённое количество записей в таблице.

N

Выражение имени таблицы.

Пример: <<date><D>><M=1><X=1>

Этот формат, описывающий таблицу с одной ячейкой (одно поле, минимальное и максимальное количество записей тоже одно). Единственное имя таблицы - "date", и его тип - Дата. См дополнительную информацию о кодировании формата ниже.

Пример: <<id><S><D=Card ID><V=<L=10 10>>><<name><S><D=Cardholder Name>><M=0><X=255>

Этот формат описывает таблицу с двумя полями, которая может содержать от 0 до 255 записей. Первое поле строки называется "id", а его описание -  "Card ID". У него есть валидатор, который ограничивает длину значения ровно до 10 знаков. Второе поле также представляет собой тип строки и называется "name".

Кодирование формата поля

field_format - это строка, описывающая одно поле в таблице данных. Оно форматируется следующим образом:

<name><type>[<F=flags>][<A=default>][<D=description>][<H=help>][<S=selection_values>][<V=validators>][<E=editor>]

У первых двух элементов нет имен. Первый элемент - имя поля, а второй содержит код типа поля (см таблицу ниже).

Имя элемента

Значение элемента

F

Отсутствие или комбинация следующих флагов:

“N” (Допускающий пустое значение (Nullable)) - указывает, что колонка может не содержать значение

“O”  (Необязательный (Optional)) - указывает, что колонка является необязательной  

“E” (Расширяемые значения выбора (Extendable selection values))– указывает, что поле может содержать значения, не перечисленные в selection_values

“R” (Только для чтения (Read only)) – указывает, что значение поля доступно только для чтения

“C” (Не реплицируется (Not replicated)) - указывает, что значение поля не реплицируется во время операции Копия таблицы данных.

“H” (Скрыт (Hidden)) – указывает, что колонка не должна быть видна во время операций с таблицей данных

“K” (Ключевое поле (Key field)) - указывает, что колонка является -- ключевым полем. Ключевые поля используются во время операции умное копирование таблицы данных. Кроме того используется валидатор ключевых полей, цель которого удостовериться, что таблица не содержит записей с равными комбинациями всех ключевых полей.

A

Значение поля, по умолчанию закодированное в строку (см раздел кодирование значения )

D

Описание поля

H

Подсказка поля (подробное описание).

S

Список значений выбора для поля. См. правила кодирования здесь.

V

Список валидаторов полей. См. правила кодирования здесь.

E

Код редактора/отрисовщика. Этот элемент активирует пользовательское визуальное представление значения поля. Поддерживаемые редакторы и отрисовщики представлены здесь.

O

Специфичные опции редактора. Опции, поддерживаемые каждым типом редактора/отрисовщика представлены здесь. Если опции редактора не определены, этот элемент должен быть опущен в определении формата таблицы.

I

Строковое ID иконки поля.

G

Группа полей.

Пример: <value><I>

Это самый простой из возможных дескрипторов формата полей, который определяет поле целых чисел, называемых "значениями".

Пример: <period><L><A=30000><D=Check Period><V=<L=100 1000000>><E=period><O=0 4>

Этот дескриптор формата определяет длинное поле (64-битное целое число) со значением по умолчанию, равным 30000. Описание поля - "Период проверки". У него есть валидатор ограничений, который  ограничивает значения, диапазон которых составляет от 100 до 1000000. Тип редактора/отрисовщика инструктирует систему использовать редактора Периода времени для редактирования значения поля.

Типы полей и кодирование значений

Код типа

Тип

Передача

Комментарии и правила кодирования значения

S

String

Да

Вставлено как есть

I

Integer


Преобразовано в строку, например 123 или -123.

L

Long


Преобразовано в строку, например 123 или -123.

B

Boolean


TRUE закодировано как строка "1", а FALSE как строка "0"

F

Float


Преобразовано в строку в соответствии с ниже приведёнными правилами. Все упомянутые символы являются символами ASCII.

  • Если аргумент - NaN, результатом будет строка NaN.

  • В ином случае результатом будет строка, представлющая знак и магнитуду (абсолютное значение) аргумента. Если знак отрицательный, первым символом результата является -; если знак положительный, в результате не появляется никакого знака. Что касается магнитуды m:

  • Если m - это бесконечность, она представлена символом Infinity; таким образом, положительная бесконечность имеет результат Infinity, а отрицательная бесконечность имеет результат -Infinity.

  • Если m нулевая, она представлена символами 0.0; таким образом, отрицательный ноль имеет результатом -0.0, а положительный ноль имеет результатом 0.0.

  • Если m больше или равно 10-3, но меньше 107, она представлена как целая часть m, в десятичной форме без начальных нулей, после которых стоит ., затем одна или несколько цифр, представляющих дробную часть m.

  • Если m меньше 10-3 или больше или равна 107, тогда она представлена так называемым "компьютеризированным экспоненциональным представлением". Пусть n будет уникальным целым числом, таким как 10n <= m < 10n+1; тогда пусть a будет математическим точным частным m и 10n, так чтобы 1 <= a < 10. Тогда магнитуда представлена как целая часть a, как одно десятичное число, после которого стоит . и десятичные числа, представлющие дробную часть a, после которой стоит буква E и представление n в виде десятичного целого.

Сколько цифр нужно ввести для дробной части m или a? Должна быть хотя бы одна цифра, чтобы представить дробную часть, плюс ровно столько цифр, сколько нужно, чтобы различить значение аргумента среди соседних значений типа Float (или Double, если обрабатывается число типа Double). То есть, предположим, что x - это точное математическое значение, представленное десятичным представлением, произведенным этим способом для конечного ненулевого аргумента d. Затем d должен стать значением типа Double, наиболее близким к x; или если два значения Double одинаково близки x, тогда d должен быть одним из них, а наименьшей мантиссой из d должен быть 0.

E

Double


Правила, как для типа Float

D

Date


Преобразовано в строку в форме "yyyy-MM-dd HH:mm:ss.SSS", где

yyyy - год

MM - месяц

dd - день месяца

HH - час (0-23)

mm -минуты

ss - секунды

SSS -миллисекунды

Конвертация должна использовать временную зону UTC.

T

Data Table

Да

Таблица с включенными данными закодирована в строку согласно правилам Кодирования таблиц данных

C

Color


Преобразовано в строку в форме "#RRGGBB", где

RR - значение красного цвета (0-255) - шестнадцатеричная форма

GG - значение зеленого цвета (0-255) -шестнадцатеричная форма

BB - значение синего цвета (0-255) - шестнадцатеричная форма

A

Data Block

Да

Конвертируется в строку в следующем виде:

Version / ID / Name / Preview_length / Data_length / Preview Data

Строка содержит несколько частей, разделенных символом /. Это следующие части:

  • Версия. Версия блока данных, кодирующего алгоритм, в данный момент 0.

  • Идентификатор. Уникальный идентификатор этого блока данных в инсталляторе SberMobile Server. Идентификатор NULL (неопределенный) представлен одним символом 0x1A (см. Кодирование значения NULL).

  • Имя. Название блока данных, обычно это имя файла, загруженного в блок данных. Имя NULL (неопределенное) представлено одним символом 0x1A (SUB) (см. Кодирование значения NULL).

  • Preview_length. Количество байтов в закодированном блоке данных предварительного просмотра. Предварительный просмотр - это краткое представление блока данных, например, черновой вариант изображения. Длина -1 означает, что предпросмотр недоступен.

  • Data_length. Количество байтов в закодированных данных. Длина -1 означает, что данные недоступны.

  • Просмотр. Закодированные байты данных просмотра блока.

  • Данные. Закодированные байты данных блока.

При перекодировании блока данных в строку байты Предпросмотра и Данных конвертируются в символы Юникода с кодами 0...255, т.е. символами ASCII.

Между полями Предпросмотр и Данные нет разделителя. Данные предпросмотра должны отделяться от основных данных в соответствии с их длиной, определённой Preview_length и Data_length.

Кодирование значений выбора

Значения для поля выбора кодируются как список элементов. Каждое имя элемента - это видимое описание значения выбора для пользователя (то, что пользователь увидит в окне списка). Значения элемента - это значение выбора, закодированное в строку, как описано в разделе кодирование значения.

Пример: список трёх значений выбора для поля с целым числом можно закодировать следующим образом: <Zero=0><One=1><Two=2>

Кодирование валидаторов

Валидаторы полей закодированы как список элементов, по одному для каждого валидатора. Имя элемента представляет собой код типа валидатора, а его значение содержит параметры, специфичные для валидатора.

Валидаторы полей

Список поддерживаемых валидаторов поля:

Код типа

Описание

Подходящие типы полей

Опции, характерные для валидатора

L

Валидатор лимитов. Проверяет, входит ли значение в диапазон, заданный параметрами валидатора.

String, Integer, Long, Float, Data

Опции валидатора закодированы в строку как два целых числа, разделённые пробелом. Первое число обозначает минимальное значение диапазона, а второе число определяет максимальное. Эти числа имеют разное значение для разных типов полей:  

Для строковых полей эти параметры ограничивают минимальную и максимальную длину строки.

Для целочисленных, длинных и плавающих полей они указывают минимальное и максимальное значение.

Для полей с данными они ограничивают число байтов, которые могут содержаться в блоке данных.

Границы включены для всех типов полей (т.е., ограничение  "3" разрешило бы строке abc - включать 3 символа).

R

Валидатор регулярных выражений. Проверяет, соответствует ли значение строки регулярному выражению, заданному параметром валидатора.

String

Строка опций валидатора содержит регулярное выражение, которому значение поля должно соответствовать. За ним может следовать (не обязательно) сообщение об ошибке, отделённой от регулярного выражения строкой ^^ . Если валидация неуспешна (т.е. значение строки не соответствует регулярному выражению), это сообщение об ошибке будет показано пользователю.

E

Валидатор выражений. Выполняет код выражения, используя значение этого поля как переменную среды {env/value}. Выражение должно вернуть логическое значение (true/false), иначе валидация не пройдёт.

Подходят все типы полей

Текст выражения.

I

Валидатор идинтификаторов. Проверяет, является ли значение уникальным среди всех значений в том же поле таблицы данных.

String, Number

Без дополнительных параметров.

N

Ненулевой валидатор. Проверяет, является ли значение ненулевым.

Подходят все типы полей

Без дополнительных параметров.

Пример 1: <L=0 255>

Если данный валидатор ограничений добавлен в формат поля строки, он разрешит лишь строки, длина которых составляет от 0 до 255 символов. Если он определён для целочисленных полей, он будет ограничивать значения полей до чисел, которые больше или равны 0 и меньше или равны 225.

Пример 2: <R=^[_A-Za-z0-9-]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(\.[_A-Za-z0-9-]+)^^Invalid E-Mail>

^[_A-Za-z0-9-]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(\.[_A-Za-z0-9-]+) -- это регулярное выражение (первый символ ^ входит в него). После этого идёт разделитель ^^ , затем следует текст сообщения об ошибке "Invalid E-Mail".

Этот валидатор регулярных выражений проверяет, содержит ли поле правильный e-mail и отправляет сообщение об ошибке Invalid E-Mail, если адрес неправильный. За дополнительной информацией о регулярных выражениях обратитесь в раздел документации Синтаксис регулярных выражений.

Валидаторы записей

Список поддерживаемых валидаторов записей:

Код типа

Описание

Опции, характерные для валидатора

K

Ключевые поля. Проверяет, существует ли комбинация значений ключевых полей в таблице. Применяется во время добавления записи.

Отсутствуют - ключевые поля помечаются флажком Ключевое поле формата.

Валидаторы таблиц

Список поддерживаемых валидаторов таблиц:

Код типа

Описание

Опции, характерные для валидатора

K

Ключевые поля. Проверяет, является ли комбинация значений ключевых полей уникальной для каждой записи.

Отсутствуют - ключевые поля отмечены флажком Ключевое поле формата.

E

Валидатор выражений. Оценивает выражение, имеющее данную таблицу как таблицу данных по умолчанию. Если выражение возвращает NULL, таблица считается верной, в ином случае вывод выражения конвертируется в строку и используется как текст сообщения об ошибке.

Текст выражения.

Пример: <E={activationThreshold} > {deactivationThreshold} ? null : 'Activation threshold must be greater than deactivation threshold'>

Проверяет, больше ли одно поле другого.

Кодировка пустых значений

Пустое значение NULL ("<Not set>") кодируется одним символом 0x1A (SUB). Это правило применяется для кодирования пустых (NULL) значения ячеек таблицы, значений по умолчанию для полей таблицы, значений выбора и любого другого места, где могут появиться значения поля.

Если для кодирования Таблицы данных используются видимые разделители, пустые (NULL) значения кодируются как символы "^".

Кодировка передачи

Значения поля кодируются при передаче для того, чтоб убрать символы, используемые форматом кодирования Таблицы данных и Коммуникационным протоколом SberMobile . Эти символы заменяются специальными шаблонами согласно следующей таблице:

Символ

Заменяется на

0x25 (%)

%%

0x02 (STX)

%^

0x0D (CR)

%$

0x17 (ETB)

%/

0x1C (FS)

%<

0x1D (GS)

%>

0x1E (RS)

%=

Обратите внимание, что шаблоны в колонке "Заменяется на" являются символьными строками - это то, что Вы видите в таблице.

Кодирование записей данных

Каждая запись данных кодируется в строку согласно следующему формату:

[<I=record_ID>]<field_value><field_value>…

Элементы без имен - это значения поля. Значения полей кодируются одно за другим, в том же порядке, как они появляются в дескрипторе формата таблиц.

Имя элемента

Значение элемента

I

ID записи (Long number)

Режимы кодирования строки

Каждую таблицу данных можно кодировать в двух режимах:

  • используя видимые разделители

  • используя невидимые разделители

Три специальных символа используются в качестве разделителей для кодирования:

Видимый разделитель

Невидимый разделитель (код)

<

0x1C

>

0x1D

=

0x1E

В этом разделе во всех примерах используются видимые разделители. Единственное ограничение при кодировании таблицы с использованием видимых разделителей - все его элементы, которые закодированы в строку, не могут содержать данные разделители.