Определение поиска

Создание поиска влечет за собой создание класса MATLAB, определяющего свойства и поведение поиска. В следующих разделах описываются шаги, необходимые для создания класса поиска. В пояснении используется класс с именем GrantFinder as an example. Код класса находится в файле, GrantFinder.m, что сопровождает этот сценарий. GrantFinder класс определяет поисковика, способного находить и форматировать гранты, присуждаемые Национальным фондом гуманитарных наук США (NEH).

Создание файла определения класса скелета

Используйте редактор MATLAB (а не Live Editor) для создания определения класса скелета, например, для поиска

Укажите базовый класс Finder

Укажите API отчетов mlreportgen.finder.Finder в качестве базового класса для поиска.

Этот базовый класс определяет свойства, общие для поисковиков, включая

mlreportgen.finder.Finder указывает другие свойства и методы, которые должно определить определение класса поиска. Это обеспечивает работу поисковика с API Report.

Определение конструктора поиска

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

GrantFinder конструктор использует MATLAB xmlread функция для чтения XML-файла разрешения с диска и преобразования его в документ Java DOM. Затем документ DOM передается в mlreportgen.finder.Finder конструктор, который устанавливает документ Java DOM как значение Container собственность. Сохранение базы данных NEH в виде документа Java DOM позволяет поисковику использовать стороннее программное обеспечение Java для поиска в базе данных. Дополнительные сведения см. в разделе Xerces Java DOM API.

Конструктор также вызывает reset функция, инициализирующая переменные, используемые для поиска в базе данных грантов. Класс GrantFinder определяет эту функцию. Аналогично, класс должен определить функцию сброса. reset функция гарантирует, что клиент может использовать ваш поисковик для проведения нескольких поисков своего контейнера. Дополнительные сведения см. в разделе Определение функции сброса.

Определение find Метод

Определите метод поиска в контейнере поиска объектов, удовлетворяющих заданным пользователем ограничениям. Метод find должен возвращать массив результирующих объектов, содержащих найденные объекты. Объекты результата являются объектами базового типа mlreportgen.finder.Result. Возврат результатов поиска как объектов результата позволяет пользователю поиска добавить результаты в отчет или главу отчета. Дополнительные сведения см. в разделе Определение результата поиска. Возврат результатов поиска в виде массива MATLAB позволяет использовать цикл для обработки результатов поиска, например

GrantFinder find метод иллюстрирует определение find способ.

Этот метод поиска использует getNodeList, функция утилиты поиска, которая GrantFinder класс определяет (см. Определение метода утилиты поиска) для поиска в базе данных грантов, удовлетворяющих ограничениям на значение свойства, указанным поисковиком Properties собственность. getNodeList функция задает внутреннее свойство с именем NodeList к результату его поиска. Результатом является Java DOM NodeList объект (NodeList), который содержит результаты поиска в виде списка элементов Java DOM (Element).

find Затем метод преобразует этот список узлов в массив результирующих объектов типа GrantResult. Он использует GrantResult конструктор для создания объекта результата предоставления из Java DOM Element объект, содержащий данные предоставления.

Определить hasNext и next Методы

Определение класса поиска должно быть определено hasNext и next методы. При первом вызове, ваш hasNext метод должен создать очередь результатов поиска и вернуть значение true, если очередь не пуста. При последующих вызовах hasNext метод должен возвращать true если очередь пуста, false в противном случае. Ваш next метод должен возвращать первый результат в очереди при первом вызове, следующий результат, следующий вызов и т.д., пока очередь не станет пустой.

Эти методы предназначены для того, чтобы позволить клиенту поиска использовать MATLAB. while loop для поиска контейнера вашего искателя, например,

GrantFinder класс иллюстрирует hasNext способ.

Этот метод сначала проверяет, была ли уже создана очередь поиска, как указано поисковиком. IsIterating собственность. Если очередь уже существует и не пуста, этот метод возвращает true. если очередь существует и пуста, этот метод возвращает false. Если очередь еще не существует (т.е. это первый вызов метода), hasNext создает очередь результатов следующим образом. Во-первых, он использует свои внутренние getNodeList метод получения грантов, соответствующих критериям поиска, указанным в Properties собственность. getNodeList метод задает свойство внутреннего поиска с именем NodeCount к числу найденных результатов. Если NodeCount больше нуля, значение hasNext метод задает внутреннее свойство с именем NextNodeIndex на 1. Искатель next метод использует это свойство для сохранения состояния очереди поиска, т.е. следующего элемента в очереди. Наконец, если очередь изначально не пуста, устройство поиска возвращает true; в противном случае false.

GrantFinder next работает с очередью, созданной hasNext способ.

Определение метода утилиты поиска

Ваш искатель find и hasNext методы должны искать в контейнере поиска объекты, удовлетворяющие ограничениям поиска. Следует рассмотреть возможность определения утилиты поиска, которую могут использовать оба метода. Например, GrantFinder hasNext и next оба метода делегируют поиск во внутреннюю утилиту с именем getNodeList. getNodeList метод в свою очередь делегирует поиск в API поиска XML-документов с именем XPath (см. Учебное пособие XPath).

Создание InvalidPropertyNames Собственность

Поисковик должен определить свойство с именем InvalidPropertyNames указывает свойства объекта, которые нельзя использовать для ограничения поиска. mlreportgen.finder.Finder базовый класс использует это свойство для проверки того, что указанные пользователем свойства поиска указаны Properties являются действительными. Если нет, базовый класс выдает ошибку. Другими словами, если клиент устанавливает Properties для недопустимых свойств, базовый класс выдает ошибку. Таким образом, базовый поиск Report API обрабатывает проверку достоверности свойств для поиска.

Если поисковик может использовать любое свойство объекта поиска в качестве ограничения поиска, он должен установить InvalidPropertyNames свойство пустое. Например, GrantFinder может обрабатывать любое свойство гранта. Поэтому оно устанавливает это свойство пустым:

Определение reset Метод

Поисковик должен иметь возможность поддерживать несколько поисков, чтобы избежать необходимости создания поиска для каждого поиска. По этой причине базовый класс поиска API Report вынуждает класс поиска определять reset метод сброса переменных, используемых логикой поиска, например:

Определение результата поиска

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

Укажите базовый класс результата

Определить mlreportgen.finder.Result в качестве базового класса для класса результата, например,

Определить Object Собственность

Определение свойства с именем Object , который клиенты результирующего объекта могут использовать для доступа к найденному объекту, содержащемуся в результирующем объекте. Определить protected в качестве SetAccess ценность вашего поиска Object собственность. Это гарантирует, что только результат может указать найденный объект, который он содержит.

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

Показать свойства найденного объекта

Ваш результат Object позволяет клиенту получить доступ к найденному объекту и, следовательно, к его свойствам. Однако для доступа к свойствам может потребоваться дополнительный код или специальные знания. Можно показать некоторые или все свойства найденного объекта в качестве свойств результирующего объекта. Например, GrantResult предоставляет следующее подмножество свойств гранта.

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

Обратите внимание, что GrantResult объединяет некоторые свойства предоставления в одно открытое свойство. Например, он предоставляет грант InstCity, InstState, InstPostalCode, и InstCountry свойства в одно свойство результата с именем Location.

В этом примере конструктор использует внутренние методы для извлечения свойств предоставления из объекта предоставления, который является Java DOM. Element объект, например,

Определение getReporter Метод

Необходимо определить метод getReporter для результирующего объекта, который возвращает объект reporter, который сообщает о найденном объекте, содержащемся в результирующем объекте. Этот метод позволяет клиенту поиска сообщать о результате операции поиска, просто добавляя результат к Report, Section, или Chapter объект. Например,

Отчет или глава add метод знает, что объект результата должен иметь getReporter метод, который возвращает репортер, который форматирует данные, содержащиеся в результате. Таким образом, при добавлении объекта результата в отчет или главу add метод вызывает результат getReporter способ получения отчета о результатах и добавление отчета о результатах к отчету или отчету, в результате чего данные о результатах форматируются и включаются в отчет.

GrantResult определение класса определяет getReporter метод, возвращающий настроенную версию API отчетов mlreportgen.report.BaseTable репортер. BaseTable репортер генерирует таблицу с пронумерованным заголовком. GrantResult класс настраивает BaseTable reporter для создания таблицы свойств гранта, например,

Следующий код показывает, как GrantResult класс настраивает BaseReporter для создания пронумерованной таблицы свойств предоставления:

Использование поиска

В этом сценарии показано, как использовать поисковик для создания отчета. Этот сценарий использует пример GrantFinder, используемый в разделе Определение Finder для создания отчета PDF по грантам NEH для учреждений в выбранных штатах с 2010 по 2012 год. Сценарий выполняет следующие задачи.

Импорт API генератора отчетов

Импортируйте классы, включенные в API отчетов генератора отчетов MATLAB. Импорт классов позволяет сценарию использовать неквалифицированные (т.е. сокращенные) имена для ссылки на классы.

import mlreportgen.report.*
import mlreportgen.dom.*

Создание контейнера отчетов

Создание контейнера PDF для отчета с помощью API отчетов mlreportgen.report.Report класс. Обратите внимание, что, поскольку сценарий импортирует API Report, он может ссылаться на класс по своему неквалифицированному имени.

rpt = Report('grant', 'pdf');

Создание страницы заголовка отчета

Добавление титульной страницы к отчету с помощью API отчетов TitlePage класс.

add(rpt, TitlePage( ...
    'Title', 'NEH Grants', ...
    'Subtitle', 'By State from 2010-2012', ...
     'Image', 'neh_logo.jpg', ...
     'Author',  'John Doe' ...
    ));

Создание оглавления отчета

Добавление оглавления с помощью API отчетов TableOfContents класс.

add(rpt, TableOfContents);

Поиск данных отчета

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

states = struct( ...
    'Name', {'California', 'Massachusetts', 'New York'}, ...
    'PostalCode', {'CA', 'MA', 'NY'}, ...
    'Grants', cell(1,3), ...
    'NGrants', cell(1,3) ...
    );

Используйте поисковик грантов для заполнения Grants и NGrants поля государственных структур. Создайте поисковик грантов.

f = GrantFinder;

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

Поиск рассматривает значения свойств как регулярные выражения. Используйте этот факт, чтобы указать диапазон значений, 2010-2012 гг., как значение YearAwarded собственность.

n = numel(states);
for i = 1:n    
    f.Properties = [
        {'InstState', states(i).PostalCode}, ...       
        {'YearAwarded', '201[0-2]'}];
    states(i).Grants = find(f);
    states(i).NGrants = numel(states(i).Grants);
end

Создание главы сводки по грантам

Создайте сводку по грантам в качестве первой главы отчета. Глава сводки по грантам содержит заголовок и сводную таблицу по грантам. В каждой строке таблицы перечисляется общее количество грантов и общая сумма денег, присужденных учреждениям штата за 2010-2012 годы. Государства появляются в таблице в порядке убывания числа грантов. Каждый штат связан гиперссылкой с главой, в которой подробно описываются гранты, присуждаемые ему.

Создание контейнера сводных глав

Начните с создания контейнера главы..

ch = Chapter('Title', 'Grant Summary');

Создание содержимого сводной таблицы предоставления

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

currencyFormatter = java.text.NumberFormat.getCurrencyInstance();

Создайте массив ячеек, содержащий содержимое заголовка таблицы.

header = {'State', 'Grants Awarded', 'Amount Awarded'};

Предварительно назначьте массив ячеек, содержащий содержимое тела таблицы. Массив ячеек имеет Rx3 строк и столбцов, где R - количество состояний, а 3 - количество сводных элементов, сообщаемых для каждого состояния.

body = cell(numel(states), 3);

Сортировка массива состояний по количеству предоставленных им грантов с помощью MATLAB sort функция. sort функция возвращает indмассив индексов к массиву состояний. Первый индекс ind массив - индекс государства с наибольшим количеством грантов, второй, со вторым наибольшим количеством грантов и т. д.

[~, ind] = sort([states.NGrants], 'descend');

Петля по состояниям по количеству грантов, заполняя сводную информацию для каждого штата. Используйте переменную, rowIdx, в качестве индекса к строке массива ячеек, соответствующей текущему состоянию.

rowIdx = 0;

Следующая строка перестраивает states массив в порядке полученных грантов и создает for цикл, который назначает каждую структуру в отсортированной states массив к переменной state на каждой итерации цикла.

for state = states(ind)

Обновите индекс строки, чтобы указать на строку массива ячеек, соответствующую текущему состоянию.

    rowIdx = rowIdx+1; 

Сценарий вводит гиперссылку на главу сведений о предоставлении для состояния в качестве первой записи в таблице для состояния, например,

В следующей строке используется DOM InternalLink для создания гиперссылки. InternalLink конструктор принимает два аргумента, идентификатор цели ссылки и текст гиперссылки. Сценарий использует почтовый индекс текущего состояния в качестве идентификатора цели ссылки, а имя штата - в качестве текста ссылки. Позже, когда сценарий создает главу с подробностями о предоставлении, он вставляет цель ссылки в заголовок главы, идентификатором которой является почтовый индекс штата. На этом создание гиперссылки завершено.

    body(rowIdx, 1) = {InternalLink(state.PostalCode, state.Name)};

Назначьте общее количество разрешений для этого состояния второму элементу в строке массива ячеек.

    body(rowIdx, 2) = {state.NGrants};
    

Вычислите общую сумму, присужденную этому государству.

    totalAwarded = 0;
    for grant = state.Grants
        totalAwarded = totalAwarded + str2double(grant.AwardAmount);
    end
    

Используйте средство форматирования валюты для форматирования общей суммы как суммы в долларах, например:

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

    body(rowIdx,3) = {char(currencyFormatter.format(totalAwarded))};
end

Чтобы создать сводную таблицу, передайте массивы заголовков и ячеек тела конструктору mlreportgen.dom.FormalTable объект.

table = FormalTable(header, body);

Формальная таблица - это таблица, имеющая заголовок и тело. FormalTable конструктор принимает два аргумента: массив ячеек, указывающий содержимое заголовка таблицы, и массив ячеек, указывающий содержимое ее тела. Конструктор преобразует содержимое массива ячеек в DOM TableRow и TableEntry объекты, определяющие таблицу, сохраняя сценарий от необходимости создания необходимых объектов таблицы.

Форматирование сводной таблицы грантов

На данном этапе сводная таблица выглядит следующим образом:

Это не очень читаемо. Заголовок имеет тот же формат, что и тело, и столбцы не разнесены.

На следующих шагах сценарий корректирует форматирование текста заголовка следующим образом:

Сначала сценарий определяет ширину и выравнивание столбцов таблицы с помощью DOM TableColSpecGroup объект. A TableColSpecGroup объект задает формат группы столбцов. Сводная таблица содержит только одну группу столбцов, поэтому сценарию необходимо создать только одну TableColSpecGroup объект.

grp = TableColSpecGroup;

TableColSpecGroup объект позволяет сценарию задать стиль по умолчанию для столбцов таблицы. Сценарий задает 1.5in как ширина колонн по умолчанию и центровая трасса как трасса колонн по умолчанию.

grp.Style = {HAlign('center'), Width('1.5in')};

Сценарий использует TableColSpec для переопределения трассы столбца по умолчанию для первого столбца.

specs(1) = TableColSpec;
specs(1).Style = {HAlign('left')};
grp.ColSpecs = specs;
table.ColSpecGroups = grp;

Примечание Сценарий может использовать до трех TableColSpec объекты, по одному для каждого столбца таблицы, для переопределения стилей столбцов группы. Первое TableColSpec объект относится к первому столбцу, ко второму столбцу и т.д. Сценарию необходимо назначить группе только один объект спецификации столбца, поскольку он переопределяет стиль по умолчанию только для первого столбца. Однако, если потребуется изменить только третий столбец, ему придется назначить три объекта спецификации столбца, оставив Style свойство первых двух столбцов объектов спецификации пусто.

Стиль таблицы по умолчанию перекрывает записи таблицы. Таким образом, сценарий использует DOM InnerMargin форматировать объект для создания некоторого пространства над записями, чтобы отделить их от записей в строке над ними. Один InnerMargin объект создает пространство (внутреннее поле) между объектом документа и объектом, содержащим его, например, между текстом в записи таблицы и границами записи таблицы. InnerMargin конструктор дополнительно принимает четыре аргумента: левое, правое, верхнее, нижнее внутренние поля объекта документа.

Сценарий использует этот конструктор для создания верхнего формата внутреннего поля из 3 точек. Затем этот формат назначается стилю записей в основной части сводной таблицы.

table.Body.TableEntriesStyle = {InnerMargin('0pt', '0pt', '3pt', '0pt')};

Наконец, сценарий форматирует заголовок таблицы, состоящий из полужирного белого текста на сером фоне:

table.Header.row(1).Style = {Bold, Color('white'), BackgroundColor('gray')}; 

Добавление сводной главы к отчету

add(ch, table);

add(rpt, ch);

Создание разделов подробных данных гранта

Петля по государственным структурам.

for state = states
    

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

    ch = Chapter('Title', {LinkTarget(state.PostalCode), state.Name});
    

Выполните цикл по результатам предоставления для состояния.

    for grant = state.Grants
        

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

        add(ch, grant);

Результат гранта имеет getReporter метод, возвращающий репортер, который создает таблицу выбранных свойств предоставления. Глава add предварительно сконфигурирован для получения репортера результата и добавления его в главу. Таким образом, добавление разрешения к главе равносильно добавлению таблицы свойств результата к главе, например,

    end
    add(rpt, ch);
end  

Закрыть объект отчета

При закрытии объекта отчета создается выходной файл PDF (grant.pdf), который указывает объект отчета.

close(rpt);

Просмотр отчета

rptview(rpt);

Приложение: База данных грантов NEH

Источником базы данных, используемой в этом примере, является Национальный фонд гуманитарных наук (НЭГ). База данных содержит информацию о грантах NEH за 2010-2019 период. Он содержит около 6000 записей в формате XML. Он доступен в NEH Grant Data. В этом примере используется локальная копия XML-файла базы данных, NEH_Grants2010s.xml.

База данных состоит из Grants элемент, содержащий набор Grant элементы, каждый из которых содержит набор элементов данных предоставления. Ниже приводится выписка из базы данных, иллюстрирующая ее структуру: