ENTAXY-374 release 1.8.2

documentation/extras/eav.adoc

@@ -0,0 +1,171 @@
+= Хранилище данных EAV
+
+== Описание модуля EXTRAS :: ENTAXY :: EAV (Entity, Attribute, Value)
+
+Хранилище данных EAV реализует модель _Сущность-Атрибут-Значение_ - это модель данных, предназначенная для описания сущностей, в которых количество атрибутов (свойств, параметров) не ограничено или не известно заранее.
+ 
+
+== Объекты модуля ЕАV
+
+image::eav_objects.png[]
+
+*Внешняя сущность*(External Entity) - любая внешняя сущность относительно модуля EAV.
+
+*Сущность EAV*(Entity EAV) - именованная сущность, связывающая аттрибуты с внешней сущностью.
+	Модуль предоставляет возможность объединять сущности EAV в одноуровневую иерархию.
+	
+*Атрибут*(Attribute) - именованный атрибут сущности EAV, содержит значение и его тип.
+
+*Типы значений:*
+
+* DOUBLE
+* LONG
+* TEXT
+* JSON
+
+
+
+
+== Использование хранилища EAV
+
+В BLUEPRINT подключаем OSGI-сервис EAVProcessor
+[source]
+----
+<reference id="eavProcessor" interface="ru.entaxy.eav.service.EAVProcessor"/>
+----
+
+в маршрутах или java коде осуществляем необходимые вызовы для создания/получения/изменения значений.
+
+*Примеры вызовов из маршрута Apache Camel XMLDSL*
+
+Создание атрибута для внешней сущности
+[source]
+----
+<bean ref="eavProcessor" method="createPrimitive('externalIdTest', 'externalTypeTest', 'entityNameTest', 'attributeNameTest', 'textValue', 'testLogin')"/>
+----
+	
+Получить все значения сохранённой сущности
+[source]
+----
+<bean ref="eavProcessor" method="getEntityWithValues('externalIdTest', 'externalTypeTest', 'entityNameTest')"/>
+----
+	
+Удалить сохранённые значения
+[source]
+----
+<bean ref="eavProcessor" method="deleteExternalEntity('externalIdTest', 'externalTypeTest')"/>
+----
+
+	
+
+== OSGI-сервис EAVProcessor.
+Сервис, выставляющий api для работы с EAV хранилищем.
+
+
+
+*Методы:*
+
+* _createPrimitive_ - простой метод сохранения примитивного значения(числового, строкового)
+* _createComplex_ - простой метод сохранения комплексного значения(JSON)
+* _getEntityWithValues_ - получение значений сущности EAV по имени
+* _fetchEntityWithValues_ - получение значений сущности EAV по имени либо null, без исключений
+* _getEntityNamedAttributes_ - получение значений с определённым именем для сущности EAV 
+* _getEntityByNameAndAttributeValue_ - получение сущности EAV по атрибуту
+* _getParentEntity_ - получение родительской сущности EAV для внешней связанной сущности
+* _getChildEntities_ - получение дочерних сущностей EAV для внешней связанной сущности с именем сущности EAV по умолчанию(PARENT)
+* _getChildEntitiesByName_ - получение дочерних сущностей EAV для внешней связанной сущности с указанным именем сущности EAV
+* _getByExternalEntity_ - получение всех сущностей EAV для внешней связанной сущности
+* _getByAttributeSet_ - получение сущностей EAV по множественным наборов параметров, каждый набор составляется из значений элементов с одним порядковым номером всех списков 
+* _updateAttribute_ - метод для изменения значения аттрибута
+* _deleteExternalEntity_ - удаление всех записей связанных с внешней сущностью
+* _deleteEntity_ - удаление именованной сущности EAV
+* _deleteAllEntityAttributes_ - удаление атрибутов именованной сущности EAV
+* _deleteAllEntityAttributesByName_ - удаление аттрибута сущности EAV с определённым наименованием 
+* _combineEntities_ - метод для объединения внешних сущностей под 1 родителем
+
+
+
+== Схема базы данных(БД).
+
+Схема БД при таком подходе остаётся неизменной независимо от состава и структуры хранимых данных.
+Бандл eav-storage разворачивает структуру из 2 таблиц:
+
+*Таблица eav_entity*
+|===
+|Слолбец	|Параметры    |Описание  
+//----------------------
+|id   
+|bigint, not null   
+|идентификатор сущности модуля EAV
+
+|external_id   
+|text, not null  
+|внешний идентификатор связываемой сущности
+
+|external_type   
+|text, not null   
+|тип связываемой сущности
+
+|name   
+|text   
+|наименование сущности модуля EAV
+
+|parent_id   
+|bigint, not null, default 0   
+|идентификатор(поле id) родительской сущности модуля EAV
+
+|create_date   
+|timestamp, not null  
+|служебное поле, дата создания
+
+|edit_date   
+|timestamp
+|служебное поле, дата изменения
+
+|created_by   
+|text, not null   
+|служебное поле, логин автора записи
+
+|external_type   
+|text   
+|служебное поле, логин последнего изменившего сущность
+|===
+
+
+*Таблица eav_attribute*
+|===
+|Слолбец	|Параметры    |Описание  
+//----------------------
+|id   
+|bigint, not null  
+|идентификатор атрибута
+
+|entity_id   
+|text, not null  
+|идентификатор сущности eav_entity
+
+|name   
+|text, not null   
+|наименование аттрибута
+
+|type   
+|text   
+|тип аттрибута
+
+|double   
+|double  
+|служебное поле для хранения значения
+
+|long   
+|bigint 
+|служебное поле для хранения значения
+
+|text   
+|text  
+|служебное поле для хранения значения
+
+|text2   
+|text   
+|служебное поле для хранения значения
+
+|===