Сервис данных

Особенности работы с объектами данных с использованием сервиса данных

Сервис данных - компонент Flexberry ORM, обеспечивающий запись и чтение объектов данных в хранилище. В объектной модели Flexberry ORM сервис данных представлен классом, реализующим интерфейс ICSSoft.STORMNET.Business.IDataService. Поддерживается несколько стандартных сервисов данных, и при необходимости пользователями могут быть разработаны новые, удовлетворяющие специфическим требованиям (например, наследуя классы ICSSoft.STORMNET.Business.ODBCDataService.ODBCDataService или ICSSoft.STORMNET.Business.SQLDataService).

Important: При обращении к сервису данных в программном коде рекомендуется производить через интерфейс ICSSoft.STORMNET.Business.IDataService, т.к. это гарантирует независимость кода от типа хранилища данных.

Перед использованием сервиса данных в программном коде его необходимо настроить тем или иным способом.

Следует обратить внимание на следующие моменты:

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

Основные возможности сервиса данных

Перед обращением в программном коде к сервису данных на него необходимо получить ссылку. При одновременном использовании нескольких хранилищ необходимо учесть некоторые особенности.

Интерфейс ICSSoft.STORMNET.Business.IDataService содержит следующие основные группы методов:

Методы с именами типа UpdateXXXXXXXX, предназначенные для приведения хранилища данных (обновление, удаление, создание записей) в соответствие с переданными одним или несколькими объектами данных:
- UpdateObject - обновление одного объекта.
- UpdateObjects - обновление нескольких объектов.
Методы с именами типа LoadXXXXXXXX, предназначенные для чтения одного, либо нескольких объектов данных.
- LoadObject - загрузка объекта (в зависимости от параметров с помощью данного метода можно осуществлять дочитку объекта).
- LoadObjects - загрузка объектов (в т.ч. перегрузки метода позволяют реализовать порционное стение, чтение принадлежащих различным классам объектов в одном представлении).
Загрузка без создания объектов LoadStringedObjectView.
Метод получения количества объектов, удовлетворяющих условию GetObjectsCount.

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

Подробнее об особенностях использовании кэша см. в статье Контекстно-зависимый кэш объектов данных.

Ниже, при рассмотрении методов, перегрузки с параметром DataObjectCache отдельно не описываются.

Загрузка объектов данных

Для загрузки нескольких объектов данных служат перегрузки метода LoadObjects.

Загрузка объектов данных по представлению или массиву представлений

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

ICSSoft.STORMNET.DataObject[] LoadObjects(ICSSoft.STORMNET.View dataObjectView);

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

ICSSoft.STORMNET.DataObject[] LoadObjects(ICSSoft.STORMNET.View[] dataObjectViews);

Параметры

dataObjectView(s) - представление или массив представлений

Загрузка объектов данных по настроечной структуре для выборки LoadingCustomizationStruct (массиву структур)

Данная перегрузка метода позволяет тонко настроить выборку загружаемых объектов за счёт использования структуры LoadingCustomizationStruct:
- указать представление (вертикальное ограничение выборки: загрузка только определенных свойств),
- количество возвращаемых строк (для реляционных хранилищ ограничение <nowiki>TOP</nowiki> в SELECT),
- параметры сортировки возвращаемых результатов (ORDER BY),
- ограничения на вычитываемые объекты данных (WHERE)
- и т.д.. Подробнее см. описание LoadingCustomizationStruct.

Пример использования.

Замечание: Данная перегрузка позволяет реализовать чтение принадлежащих различным классам объектов в одном представлении.

// 1.
ICSSoft.STORMNET.DataObject[] LoadObjects(LoadingCustomizationStruct customizationStruct);

// 2.
ICSSoft.STORMNET.DataObject[] LoadObjects(LoadingCustomizationStruct customizationStruct, DataObjectCache DataObjectCache);

Происходит последовательный вызов метода с параметром - LoadingCustomizationStruct для каждого элемента массива. Практическая применимость данной перегрузки неочевидна.

ICSSoft.STORMNET.DataObject[] LoadObjects(LoadingCustomizationStruct[] customizationStructs);

Параметры

customizationStruct(s) - настроечная структура для выборки (массив структур)

Загрузка объектов с использованием состояния вычитки (для реализации порционного чтения)

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

// 1.
ICSSoft.STORMNET.DataObject[] LoadObjects(LoadingCustomizationStruct customizationStruct,ref object State);

// 2.
ICSSoft.STORMNET.DataObject[] LoadObjects(LoadingCustomizationStruct customizationStruct, ref object State, DataObjectCache DataObjectCache);

Получение очередных порций при порционном чтении. Должен предшествовать вызов в указанной выше перегрузке.

// 1.
ICSSoft.STORMNET.DataObject[] LoadObjects(ref object State);

// 2.
ICSSoft.STORMNET.DataObject[] LoadObjects(ref object State, DataObjectCache DataObjectCache);

Параметры

State - Состояние вычитки(для последующей дочитки)
customizationStruct - настроечная структура для выборки

Примечание: Размер порции может быть задан с помощью параметра LoadingBufferSize структуры LoadingCustomizationStruct.

Загрузка одного объекта данных

Для загрузки одного объекта данных служат перегрузки метода LoadObject. Вычитка свойств из хранилища осуществляется по заданному в объекте данных первичному ключу.

Примеры использования:

Загрузка объекта данных по первичному ключу

Будут загружены только собственные свойства объекта. При отсутствии в хранилище данных объекта с заданным первичным ключом будет выдано исключение CantFindDataObjectException. Не следует использовать данную перегрузку метода для дочитки объекта данных, для этого применимы перегрузки методы с дополнительными параметрами.

// 1.
void LoadObject(ICSSoft.STORMNET.DataObject dobject)

// 2.
void LoadObject(ICSSoft.STORMNET.DataObject dobject, DataObjectCache DataObjectCache)

Параметры

dobject - Объект данных, который требуется загрузить

Загрузка объекта данных по представлению

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

// 1.
void LoadObject(string dataObjectViewName, ICSSoft.STORMNET.DataObject dobject)

// 2.
void LoadObject(void LoadObject(ICSSoft.STORMNET.View dataObjectView, ICSSoft.STORMNET.DataObject dobject)

// 3.
void LoadObject(string dataObjectViewName, ICSSoft.STORMNET.DataObject dobject, DataObjectCache DataObjectCache)

// 4.
void LoadObject(ICSSoft.STORMNET.View dataObjectView, ICSSoft.STORMNET.DataObject dobject, DataObjectCache DataObjectCache)

Параметры

dataObjectView(dataObjectViewName) - представление (имя представления)

Загрузка объекта данных с указанием дополнительных параметров

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

// 1.
void LoadObject(ICSSoft.STORMNET.DataObject dobject, bool ClearDataObject, bool CheckExistingObject)

// 2.
void LoadObject(string dataObjectViewName, ICSSoft.STORMNET.DataObject dobject, bool ClearDataObject, bool CheckExistingObject)

// 3.
void LoadObject(ICSSoft.STORMNET.View dataObjectView, ICSSoft.STORMNET.DataObject dobject, bool ClearDataObject, bool CheckExistingObject)

// 4.
void LoadObject(ICSSoft.STORMNET.DataObject dobject, bool ClearDataObject, bool CheckExistingObject, DataObjectCache DataObjectCache) 

// 5.
void LoadObject(string dataObjectViewName, ICSSoft.STORMNET.DataObject dobject, bool ClearDataObject, bool CheckExistingObject, DataObjectCache DataObjectCache)

// 6.
void LoadObject(ICSSoft.STORMNET.View dataObjectView, ICSSoft.STORMNET.DataObject dobject, bool ClearDataObject, bool CheckExistingObject, DataObjectCache DataObjectCache)

Параметры

ClearDataObject - очищать ли объект
CheckExistingObject - проверять ли существование объекта в хранилище (если указать true, при отсутствии объекта в базе будет выдано исключение типа CantFindDataObjectException)

Обновление одного объекта данных

Для обновления одного объекта данных служат перегрузки метода UpdateObject.

Примеры использования:

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

Следует иметь в виду, что сохранение объекта может вызвать сохранение связанных с ним объектов.

Обновление объекта данных.

// 1.
void UpdateObject(ICSSoft.STORMNET.DataObject dobject) 

// 2.
void UpdateObject(ref ICSSoft.STORMNET.DataObject dobject) 

// 3.
void UpdateObject(ICSSoft.STORMNET.DataObject dobject, DataObjectCache DataObjectCache) 

// 4.
void UpdateObject(ref ICSSoft.STORMNET.DataObject dobject, DataObjectCache DataObjectCache) 

// 5.
void UpdateObject(ICSSoft.STORMNET.DataObject dobject, bool AlwaysThrowException) 

// 6.
void UpdateObject(ref ICSSoft.STORMNET.DataObject dobject, bool AlwaysThrowException) 

// 7.
void UpdateObject(ref ICSSoft.STORMNET.DataObject dobject, DataObjectCache DataObjectCache, bool AlwaysThrowException) 

Параметры

dobject - объект данных, который требуется обновить
DataObjectCache - кеш объектов
AlwaysThrowException - Если произошла ошибка в базе данных, не пытаться выполнять других запросов, сразу взводить ошибку и откатывать транзакцию

Обновление нескольких объектов данных

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

Обновляемые объекты данных могут быть как однотипными, так и разнотипными. В метод они передаются параметром — одномерным массивом типа DataObject[]. В общем случае сервис данных умеет сам выстраивать порядок запросов на обновление объектов данных. Но возможны ситуации, когда для связанных объектов важен порядок следования объектов в массиве, подробная информация о порядке сохранения объектов приведена в статье Обработка множества объектов.

Следует иметь в виду, что для каждого элемента массива его сохранение может вызвать сохранение связанных с ним объектов.

Пример использования.

Обновление нескольких объектов данных в хранилище.

// 1.
void UpdateObjects(ref ICSSoft.STORMNET.DataObject[] objects)

// 2.
void UpdateObjects(ref ICSSoft.STORMNET.DataObject[] objects, bool AlwaysThrowException)

// 3.
void UpdateObjects(ref ICSSoft.STORMNET.DataObject[] objects, DataObjectCache DataObjectCache)

// 4.
void UpdateObjects(ref ICSSoft.STORMNET.DataObject[] objects, DataObjectCache DataObjectCache, bool AlwaysThrowException)

Параметры

objects - объекты для обновления
DataObjectCache - кеш объектов
AlwaysThrowException - если произошла ошибка в базе данных, не пытаться выполнять других запросов, сразу взводить ошибку и откатывать транзакцию

Загрузка без создания объектов

Можно выполнить загрузку из хранилища без создания экземпляров: каждый объект в этом случае представлен в виде строки из значений свойств с разделителями. Используется, когда не требуется редактирование объектов. Данный метод намного быстрее, чем создание объектов при загрузке в методе LoadObjects. Для загрузки в виде строкового представления предназначены перегрузки метода LoadStringedObjectView.

Пример использования.

Возвращаемый результат: массив структур ObjectStringDataView

ObjectStringDataView[] LoadStringedObjectView(char separator, LoadingCustomizationStruct customizationStruct)

Параметры

separator - разделитель в строках
customizationStruct - настроичная структура для выборки LoadingCustomizationStruct

Примечание: порядок следования свойств объекта данных в результирующей строке с разделителями задаётся парметром ColumnsOrder структуры customizationStruct.

Загрузка без создания объектов с использованием состояния вычитки (для реализации порционного чтения)

1.LoadStringedObjectView

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

ObjectStringDataView[] LoadStringedObjectView(char separator, LoadingCustomizationStruct customizationStruct, ref object State)

Получение очередных порций при порционном чтении. Должен предшествовать вызов в предыдущей перегрузке.

ObjectStringDataView[] LoadStringedObjectView(ref object state)

2.CompleteLoadStringedObjectView

Корректное завершения операции порционного чтения при LoadStringedObjectView.

void CompleteLoadStringedObjectView(ref object state)

Параметры

State - Состояние вычитки(для последующей дочитки)
customizationStruct - настроечная структура для выборки

Примечание: Размер порции может быть задан с помощью параметра LoadingBufferSize структуры LoadingCustomizationStruct.

Получение количества объектов, удовлетворяющих запросу

Пример использования.

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

GetObjectsCount

int GetObjectsCount(LoadingCustomizationStruct customizationStruct)

Параметры

customizationStruct - настроечная структура для выборки LoadingCustomizationStruct

Использование SQL при работе с сервисом данных

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

Асинхронные запросы в ORM

В ORM существует возможность загружать данные в асинхронном режиме (async/await). SQLDataService реализует интерфейс IAsyncDataService, который описывает асинхронные методы загрузки.

Подробнее в статье Асинхронные запросы в ORM.